my_site/NEXT_CODEX_HANDOFF.md

项目交接说明

更新时间：2026-03-18
项目根目录：/Users/mac/Documents/my_site

1. 项目概况

这是一个前后端分离的个人门户项目：

• 前端：front/
• 后端：backend/
• 线上主站：https://yoyuzh.xyz
• 线上 API：https://api.yoyuzh.xyz

主要功能：

• 登录 / 注册
• 网盘文件列表与最近文件
• 教务相关接口（课表 / 成绩）

2. 当前线上架构

当前建议保持的生产架构是：

• yoyuzh.xyz：继续走 OSS / ESA，负责静态站点
• api.yoyuzh.xyz：直接指向后端服务器，不要继续走 ESA 代理

原因：

• 主站静态资源走 ESA 没问题
• API 一旦走 ESA，之前出现过：
  • 525 Origin SSL Handshake Error
  • ERR_CONNECTION_CLOSED
  • ERR_EMPTY_RESPONSE
• 当前最稳方案是“静态站加速，API 直连”

3. 当前前端生产配置

文件：

• front/.env.production

当前应保持为：

VITE_API_BASE_URL="https://api.yoyuzh.xyz/api"
VITE_ROUTER_MODE="hash"
VITE_ENABLE_DEV_LOGIN="false"

说明：

• 不要再切回同域 /api，除非以后重新正确配置边缘转发
• 目前生产前端已经恢复为直连 api.yoyuzh.xyz

4. 当前已完成的前端改动

4.1 登录页

front/src/pages/Login.tsx

• 已替换为模板版登录 / 注册页
• 登录调用：POST /auth/login
• 注册调用：POST /auth/register
• 登录成功后写入 session 并跳转 /overview

4.2 网络错误处理

front/src/lib/api.ts

• 对网络错误统一包装为更清晰的前端错误
• 登录和只读接口有轻量重试机制
• 当前策略是“尽量兜底，但不要把登录拖到 7-8 秒”

4.3 登录成功与总览初始化失败拆分提示

相关文件：

• front/src/lib/session.ts
• front/src/pages/Overview.tsx
• front/src/pages/overview-state.ts

已做：

• 登录成功后会标记一次“post-login pending”
• /overview 初始化失败时，会提示“登录已成功，但总览加载失败”
• 避免把 overview 并发初始化失败误判成登录失败

5. 当前后端与服务器状态

通过 SSH 已确认：

• my-site-api.service 正常运行
• 后端本机 127.0.0.1:8080 正常
• 服务器本机直打登录接口返回 200
• Nginx 正常反代 api.yoyuzh.xyz -> 127.0.0.1:8080

服务器上关键配置：

• Nginx：/etc/nginx/sites-enabled/my-site-api
• 后端配置：/opt/yoyuzh/application-prod.yml
• 服务名：my-site-api.service

6. 线上排查结论

6.1 已确认不是后端业务慢

在服务器本机测试结果：

• POST http://127.0.0.1:8080/api/auth/login 约 95ms
• POST https://api.yoyuzh.xyz/api/auth/login 从服务器发起约 681ms

所以：

• 后端本身不是“登录 5 秒”的根因

6.2 之前登录很慢的主要原因

更像是以下问题叠加：

• 旧 DNS / 旧代理链路未收敛
• API 域名曾被 ESA 代理，导致 TLS / 回源问题
• 浏览器前链路偶发 ERR_CONNECTION_CLOSED

6.3 当前更可信的状态

服务器日志已经看到真实浏览器请求成功：

• OPTIONS /api/auth/login => 200
• POST /api/auth/login => 200
• /api/user/profile => 200
• /api/files/recent => 200
• /api/files/list => 200
• /api/cqu/* => 200

因此：

• 现在如果仍有个别客户端不稳定，优先怀疑本地 DNS / 浏览器缓存 / 本地网络链路

7. DNS / ESA 方面的重要结论

7.1 过去踩过的坑

不要再轻易做下面这件事：

• 让 yoyuzh.xyz/api/* 通过 ESA 回源到 API

之前已经明确踩到：

• /api/* 误回 OSS，报 403 NonCnameForbidden
• 回源 HTTPS 握手失败，报 525 Origin SSL Handshake Error

7.2 当前建议

• yoyuzh.xyz：可以继续 ESA
• api.yoyuzh.xyz：不要走 ESA 代理

7.3 用户侧现象

曾出现：

• 无痕模式能登录
• 本机 dig 还查到旧的 198.18.0.148

这说明某一阶段存在 DNS 传播不一致。
如果下一个 Codex 遇到“浏览器能用，命令行不行”的情况，先查 DNS 链路，不要直接改代码。

8. OSS 前端部署方式

已经写好自动部署脚本：

• scripts/deploy-front-oss.mjs
• 配套库：scripts/oss-deploy-lib.mjs
• 配置模板：.env.oss.example

8.1 本地使用方式

先准备：

cp .env.oss.example .env.oss.local

然后填入 OSS 参数。

8.2 发布命令

./scripts/deploy-front-oss.mjs

8.3 只看将要上传什么

./scripts/deploy-front-oss.mjs --skip-build --dry-run

8.4 部署逻辑

脚本会：

• 读取 .env.oss.local
• 构建 front/dist
• 上传到 OSS
• 自动设置缓存头

缓存策略：

• index.html => no-cache
• assets/* => public,max-age=31536000,immutable

9. 测试账号

开发测试账号文档：

• 开发测试账号.md

常用账号：

• portal-demo / portal123456

注意：

• 这些开发账号只在特定环境下才会自动初始化
• 如果线上账号密码不对，不要默认认为后端坏了

10. SSH 与敏感信息

有 SSH 凭据文件：

• 账号密码.txt

下一个 Codex 可以读取该文件用于 SSH，但不要在普通交互回复里直接回显其中的明文密码。

11. 推荐的排查顺序

如果后续又出现“登录失败 / 网络连接异常”，按这个顺序排：

1. 先查前端当前生产包是否正确

   • 看 https://yoyuzh.xyz/ 的 index.html
   • 确认引用的是最新构建产物

2. 再查 API 域名是否直连服务器

   • dig +short api.yoyuzh.xyz
   • curl -vkI https://api.yoyuzh.xyz/

3. 再查服务器本机和 systemd

   • systemctl status my-site-api
   • curl http://127.0.0.1:8080/...

4. 最后查 Nginx access/error log

   • /var/log/nginx/access.log
   • /var/log/nginx/error.log

不要上来就改前端逻辑。

12. 当前最重要的改进建议

短期建议

• 保持 API 直连，不再给 api.yoyuzh.xyz 套 ESA
• 用现有自动部署脚本发布前端

中期建议

• 给后端加一个明确的健康检查接口，比如 /api/healthz
• 给 Nginx access log 加 upstream timing 和 request id

长期建议

• 如果未来还想做同域 /api，要单独做一轮边缘转发设计
• 先确保：
  • 源站类型正确
  • 不会回 OSS
  • 不会再发生 525

13. 给下一个 Codex 的一句话总结

当前项目已经从“链路混乱”恢复到“后端基本正常、主站正常、前端直连 API”的状态。
接手时优先维持现状，不要贸然重新启用 ESA 的 /api 回源方案。