281 lines
6.5 KiB
Markdown
281 lines
6.5 KiB
Markdown
# 项目交接说明
|
||
|
||
更新时间：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`
|
||
|
||
当前应保持为：
|
||
|
||
```env
|
||
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 本地使用方式
|
||
|
||
先准备：
|
||
|
||
```bash
|
||
cp .env.oss.example .env.oss.local
|
||
```
|
||
|
||
然后填入 OSS 参数。
|
||
|
||
### 8.2 发布命令
|
||
|
||
```bash
|
||
./scripts/deploy-front-oss.mjs
|
||
```
|
||
|
||
### 8.3 只看将要上传什么
|
||
|
||
```bash
|
||
./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` 回源方案。
|