在分布式系统中，时间处理是沉默的基石，它要么稳固地支撑着业务，要么就成为难以追踪的“幽灵Bug”的温床。本文详细记录了一次从陈旧的java.util.Date和模糊的时区约定，到基于java.time和UTC的现代化时间体系的完整迁移过程，并提供一个从数据库到API的全栈、可落地的实施指南，旨在帮助开发者彻底告别时区带来的混乱。

1. 问题的起点：那些熟悉的“时间之痛”

我们的重构之旅始于一系列典型但危险的症状：

环境强耦合：应用部署在特定时区（例如 UTC+3）的服务器上，java.util.Date的行为恰好与数据库TIMESTAMP类型“看起来”一致。这是一种危险的巧合，系统行为依赖于部署环境，一旦环境变更，后果不堪设想。
诡异的数据显示：当我们将数据库字段升级为TIMESTAMPTZ（Timestamp with Time Zone）后，存入的UTC时间在数据库客户端中却显示为另一个完全不相关的时区（例如 UTC+8）。这让团队对数据的准确性产生了巨大困惑。
潜在的夏令时（DST）灾难：现有模型完全没有考虑夏令时，定时任务、跨时区报表和业务逻辑在夏令时切换的瞬间，都可能出现偏差或彻底失效。
脆弱的API契约：前后端或服务间通过毫秒时间戳或格式模糊的字符串（如 "2023-10-26 10:00:00"）传递时间，时区信息完全丢失，依赖双方的“默契”，极易出错。

我们的目标明确：构建一个环境无关、时区明确、类型安全、契约标准的现代化时间处理体系。

2. 深入诊断：两个决定性的“Aha!”时刻

在着手改造前，我们必须成为侦探，弄清问题的根源。两个关键的调查过程为我们指明了方向。

2.1 Aha #1：揭开 `TIMESTAMPTZ` 的神秘面纱

现象：存入的UTC时间，为何在数据库客户端显示为东八区时间？

调查：我们在数据库客户端（如 DBeaver, Navicat）执行了一个简单的命令：

sql
SHOW timezone;

结果： Asia/Shanghai

结论：这个结果瞬间揭示了TIMESTAMPTZ的核心工作机制，这也是许多开发者最容易误解的地方：

存储（Storage）：TIMESTAMPTZ 在物理上永远以UTC格式存储一个绝对的时间点。它本身不存储任何时区信息。
显示（Display）：当你查询一个TIMESTAMPTZ字段时，数据库服务器会根据当前数据库会话（Session）的timezone设置，对存储的UTC值进行动态转换后再呈现给你。

因此，我们看到的 +08:00 只是一个显示层的本地化，数据本身是正确无误的。这个发现让我们明白，解决问题的关键在于应用层，而非修改数据库时区。

2025-08-28

Nginx 代理 504？一场由 Docker 与 firewalld 引发的深度网络排查之旅

一、问题的起点：一个简单的 504 Gateway Timeout

故事始于一个看似非常普遍的场景：我部署了一个 Nginx 反向代理服务（Nginx Proxy Manager，运行在 Docker 中），用于代理另一台服务器上的 Dify 应用。

服务器 A：运行 Nginx Proxy Manager (NPM) 的 Docker 容器。
服务器 B：运行 Dify 应用，监听在 [Server_B_IP]:80。症状：
通过浏览器直接访问 http://[Server_B_IP]，一切正常。
通过手机等外部网络访问 http://[Server_B_IP]，也一切正常。
通过配置好的域名 your.domain.com 访问，Nginx 代理返回 504 Gateway Timeout。这通常意味着代理服务器（NPM）在规定时间内没有从上游服务器（Dify）收到响应。但既然 Dify 服务本身是好的，问题显然出在从“服务器 A”到“服务器 B”的连接路径上。

二、第一阶段：常规排查与常见误区

按照标准流程，我们首先排查了最常见的可能性。

1. 检查 Nginx 代理配置

proxy_pass 地址：确认 NPM 中配置的目标地址是正确的 http://[Server_B_IP]:80。
超时设置：检查 proxy_read_timeout 等超时参数，确认时间足够长。
请求头 (proxy_set_header)：确保 Host 等关键请求头被正确传递。结论：配置从逻辑上看没有问题。

2. 检查后端服务状态

我们已经通过外部网络直接访问验证了 Dify 服务是健康且可达的。 阶段性结论：问题不在应用层，而在网络层。Nginx 配置和服务本身都是好的，但 NPM 容器本身无法连接到 Dify 服务器。

阅读全文

问题：从镜像恢复云服务器后 SSH 登录失败 (/bin/bash: Permission denied) 的解决之道

AI撰写

一、问题现象：诡异的 SSH 登录失败

从混乱到清晰：一次完整的Java时间体系现代化重构实战