docs: 更新 5/22 工作日志 — 安全组打通 + 去掉降级 + admin部署 + API流水线修复

chore: update README and cleanup planning docs
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-22 10:14:35 +08:00 · 2026-05-22 09:18:23 +08:00
3 changed files with 183 additions and 69 deletions
--- a/README.md
+++ b/README.md
@ -77,9 +77,15 @@
 |------|------|
 | [设计文档](技术设计/web-projects/设计文档.md) | 官网视觉设计系统："Luminous Clarity" 玻璃拟态浅色主题 |

+### admin-projects（管理后台）
+
+| 文档 | 说明 |
+|------|------|
+| [项目 README](../admin-projects/README.md) | 技术栈、目录结构、认证流程、角色体系 |
+
 ### 预留目录

-`miniapp-projects` `harmonyos-projects` `admin-projects` `android-projects` `webApp-projects` — 暂无文档。
+`miniapp-projects` `harmonyos-projects` `android-projects` `webApp-projects` — 暂无文档。

 ---

--- a/工作日志/2026-05-22.md
+++ b/工作日志/2026-05-22.md
@ -2,7 +2,7 @@

 ---

-## 一、Admin 项目架构修复
+## 一、Admin 项目架构修复（凌晨）

 ### 1. admin-ai-chat 模块部署 ✅

@ -34,47 +34,189 @@
 - ✅ UFW 开放 8642（仅内网 172.21.0.0/16 + 10.2.0.0/16）
 - ✅ NestJS `AdminAiChatService` 改为 Hermes 优先 + DeepSeek 降级

-**当前架构：**
-```
-Admin 前端 (Vite)
-  → POST /admin-api/ai/chat (Bearer token)
-  → NestJS AdminAiChatService (8核32G)
-    → 尝试 http://10.2.0.7:8642/v1/chat/completions (Hermes)
-    → 失败则降级 DeepSeekProvider
-```
+---

-**待修复：**
- ⏳ 腾讯云安全组需手动开通 8642 端口（仅对内网），当前 8核32G → 4核4G:8642 不通
- ⏳ 临时方案：NestJS 自动降级到 DeepSeek 直接调用，Admin Chat 功能可用
+## 二、内网安全组排查与打通 ✅
+
+### 问题
+蜂驰云 8核32G（172.21.0.4）→ 轻量云 4核4G（10.2.0.7）:8642 不通
+
+### 排查过程
+1. SSH 到两台服务器实测
+2. 内网 ping 通（1.8ms）
+3. 轻量云 UFW 已放行 172.21.0.0/16 → :8642
+4. iptables 里 `YJ-FIREWALL-INPUT` 链（腾讯云 Lighthouse 防火墙）拦截
+5. 根因：**控制台防火墙未添加 8642 规则**
+
+### 修复
+- 腾讯云控制台 → Lighthouse → 81.70.187.179 → 防火墙 → 添加 TCP 8642，来源 172.21.0.4
+- 连通后 curl 测试：http_code=200，延迟 2.84s ✅

 ---

-## 二、服务器状态
+## 三、去掉 DeepSeek 降级逻辑 ✅
+
+**原因：** Hermes 优先 + DeepSeek 降级的设计导致不知道实际用了哪个服务。
+
+**改动：**
+- `admin-ai-chat.service.ts`：移除 `DeepSeekProvider` 注入和 `callDeepSeek` 方法
+- `admin-ai-chat.module.ts`：移除 `DeepSeekProvider` 注册
+- Hermes 挂了直接抛错，不再静默降级
+
+**全链路架构（最终版）：**
+```
+Admin 前端 (Vite) → POST /admin-api/ai/chat
+  → NestJS AdminAiChatService (8核32G)
+    → POST http://10.2.0.7:8642/v1/chat/completions (Hermes)
+    → 失败直接报错，前端可见
+```
+
+---
+
+## 四、Admin 前端部署 ✅
+
+### 部署配置
+
+| 项目 | 值 |
+|------|-----|
+| 域名 | `https://admin.longde.cloud` |
+| 服务器 | 蜂驰云 8核32G (120.53.227.155) |
+| 部署目录 | `/opt/zhixi/admin/dist/` |
+| Web 服务器 | Nginx（SPA fallback + 静态资源缓存） |
+| SSL | Let's Encrypt，2026-08-20 到期，自动续期 |
+
+### Nginx 配置
+- `/` → SPA fallback `try_files $uri /index.html`
+- `/assets/` → 1年缓存
+- HTTP → HTTPS 自动跳转
+
+### CI/CD 流水线
+```
+push main → prod runner
+  → git clone http://10.2.0.7:3000/wangdl/admin-projects.git
+  → npm ci → npm run build
+  → rsync dist/ → /opt/zhixi/admin/dist/
+  → nginx reload
+  → curl 健康检查
+```
+
+---
+
+## 五、修复 API 部署流水线 ✅
+
+### 发现的问题
+旧 workflow 只部署了 RAG Worker，**NestJS 代码不会自动更新**！
+
+### 旧流水线（有缺陷）
+| 步骤 | 状态 |
+|------|------|
+| git clone/pull | ✅ |
+| npm ci | ❌ 缺失 |
+| prisma generate | ❌ 缺失 |
+| nest build | ❌ 缺失 |
+| prisma migrate deploy | ❌ 缺失 |
+| rsync dist/node_modules/prisma | ❌ 缺失 |
+| restart zhixi-api | ❌ 缺失 |
+| deploy RAG Worker | ✅ |
+| health check | ✅ |
+
+### 新流水线
+```
+push main → prod runner
+  → git clone/pull
+  → npm ci
+  → prisma generate + nest build
+  → docker start mysql/redis/qdrant
+  → 清理失败 migration
+  → prisma migrate deploy
+  → rsync dist/ node_modules/ prisma/ package.json → /opt/zhixi/backend/
+  → systemctl restart zhixi-api
+  → deploy RAG Worker + restart zhixi-worker
+  → curl health check
+```
+
+### 踩坑
+- `prisma migrate deploy` 报错 exit code 1 → 缺少 `DATABASE_URL` 环境变量，workflow 顶部加 `env` 解决
+
+---
+
+## 六、Hermes api_server 架构确认
+
+### Gateway 配置
+```
+/opt/data/.env:
+  API_SERVER_ENABLED=true
+  API_SERVER_KEY=zhixi-hermes-key-2026
+  API_SERVER_HOST=0.0.0.0
+  API_SERVER_PORT=8642
+
+/opt/data/config.yaml:
+  model: deepseek-v4-flash
+  provider: custom
+  base_url: https://api.deepseek.com/v1
+  api_key: sk-ddddea4986d843be978ced9e82988fa0
+```
+
+### gateway_state.json
+```json
+{
+  "pid": 91,
+  "gateway_state": "running",
+  "platforms": {
+    "api_server": {
+      "state": "connected",
+      "updated_at": "2026-05-21T16:26:56Z"
+    }
+  }
+}
+```
+
+### api_server.py 端点
+- `POST /v1/chat/completions` — OpenAI Chat 格式
+- `POST /v1/responses` — OpenAI Responses 格式
+- `GET /v1/models` — 模型列表
+- `GET /v1/capabilities` — API 能力声明
+- `POST /v1/runs` — 启动 run（异步）
+- `GET /health` — 健康检查
+
+---
+
+## 七、服务器状态（最终）

 ### 8核32G (120.53.227.155)

 | 服务 | 状态 |
 |------|------|
-| zhixi-api | ✅ active |
-| zhixi-worker | ✅ active |
-| gitea-runner | ✅ active |
+| zhixi-api | ✅ active，支持自动部署 |
+| zhixi-worker | ✅ active，支持自动部署 |
+| gitea-runner (prod) | ✅ active |
 | MySQL/Redis/Qdrant | ✅ 运行中 |
-| admin-ai-chat 端点 | ✅ `POST /admin-api/ai/chat` |
-| admin dashboard 端点 | ✅ `GET /admin-api/ai/dashboard` |
+| admin.longde.cloud | ✅ HTTPS，自动部署 |
+| api.longde.cloud | ✅ HTTPS |

 ### 4核4G (81.70.187.179)

 | 服务 | 状态 |
 |------|------|
-| hermes-agent | ✅ Up，Dashboard :9119，API :8642 |
+| hermes-agent | ✅ Dashboard :9119，API :8642 |
 | Gitea 1.23.8 | ✅ |
 | Nginx | ✅ |
-| gitea-runner | ✅ |
+| gitea-runner (web) | ✅ |
 | UFW | ✅ 22/80/443/2222/9119/8642 |

+### 部署流水线对比
+
+| | api-server | admin-projects |
+|------|------|------|
+| 仓库 | suche-Hermes/api-server | wangdl/admin-projects |
+| Runner | prod | prod |
+| 构建 | npm ci → nest build | npm ci → vite build |
+| 部署 | rsync → systemctl restart | rsync → nginx reload |
+| 域名 | api.longde.cloud | admin.longde.cloud |
+
 ---

-## 三、当前待办（更新）
+## 八、当前待办

 ### 已完成
 1. ~~admin-ai-chat 模块部署~~ ✅
@ -85,15 +227,18 @@ Admin 前端 (Vite)
 6. ~~Hermes Gateway 启动~~ ✅
 7. ~~Hermes api_server 平台启用~~ ✅
 8. ~~NestJS → Hermes 优先调用~~ ✅
+9. ~~腾讯云安全组添加 8642 端口~~ ✅
+10. ~~去掉 DeepSeek 降级逻辑~~ ✅
+11. ~~Admin 前端部署 + HTTPS~~ ✅
+12. ~~API 部署流水线修复~~ ✅

 ### 待完成
-9. ⏳ 腾讯云安全组添加 8642 端口（需手动操作控制台）
-10. ⏳ 4核4G Nginx 代理 `/hermes-api/` → `127.0.0.1:8642`
-11. 🟢 AI 提取 prompt 调优（待真实文档）
-12. 🟢 COS 备份同步 + 生命周期清理
-13. 🟢 MySQL 物理清理脚本
-14. 🟢 Docker Compose 统一
-15. 🟢 logrotate 确认
-16. 🔴 学习引擎串联（待产品决策 → `待决策事项.md`）
-17. ⬜ 阶段九：iOS API 对接 + 用户闭环测试
-18. ⬜ 阶段十：后台管理 + 额度检查
+13. ⏳ 4核4G Nginx 代理 `/hermes-api/` → `127.0.0.1:8642`
+14. 🟢 AI 提取 prompt 调优（待真实文档）
+15. 🟢 COS 备份同步 + 生命周期清理
+16. 🟢 MySQL 物理清理脚本
+17. 🟢 Docker Compose 统一
+18. 🟢 logrotate 确认
+19. 🔴 学习引擎串联（待产品决策 → `待决策事项.md`）
+20. ⬜ 阶段九：iOS API 对接 + 用户闭环测试
+21. ⬜ 阶段十：后台管理 + 额度检查
--- a/长期规划/[参考]-技术与交付模块.md
+++ b/长期规划/[参考]-技术与交付模块.md
@ -1,37 +0,0 @@
-# 技术与交付模块
-
-## 模块目标
-
-确定技术方向和交付策略。
-
---
-
-## 技术方向
-
- **Apple-first**：优先 iOS（Swift/SwiftUI），后续扩展 iPad/Mac
- **后端**：模块化架构，按业务域拆分
- **AI**：Provider 抽象层，按任务分级路由模型（轻任务用便宜模型，核心分析用主力模型）
- **部署**：单服务器起步，后续按需扩展
- **官网**：静态生成，SEO 友好
-
---
-
-## 交付节奏
-
-按业务流程逐个交付，每个流程走通前后端联调后再做下一个。
-
---
-
-## 第一版范围
-
-**做：** iOS 客户端、核心学习闭环、AI 分析、Apple IAP
-
-**暂不做：** 安卓、Web 学习端、复杂后台
-
---
-
-## 核心原则
-
- 从"业务分级工作流"开始，暂不做完全自治 Agent
- 先验证核心闭环，再扩展平台
- 模型路由：基础档不默认使用高价模型，高级推理作为 Pro 权益
Author	SHA1	Message	Date
WangDL	10b2def872	docs: 更新 5/22 工作日志 — 安全组打通 + 去掉降级 + admin部署 + API流水线修复	2026-05-22 10:14:35 +08:00
WangDL	d6bdcb40cc	chore: update README and cleanup planning docs Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-22 09:18:23 +08:00