开发流程指南

本文档介绍智恒项目的架构、开发工作流以及安全规范。

架构概览

我们的生产系统运行在一台云服务器上，使用 Docker Compose 管理 7 个服务：

服务	容器名	端口	用途
Nginx	zhiheng-nginx-1	:8888	反向代理、安全头、前端托管
前端	zhiheng-frontend-1	内部 :80	Vue 3.5+Vite SPA
后端	zhiheng-backend-1	内部 :8000	FastAPI (认证、课程、聊天、RAG)
LightRAG	zhiheng-lightrag-1	:9621	基于图的知识库 (PostgreSQL+AGE)
DeerFlow	zhiheng-deerflow	:8001	AI 智能体平台 (工具、技能、PPT生成)
数据库	zhiheng-db	内部 :5432	pgvector + AGE 图扩展
Redis	zhiheng-redis-1	:6379	聊天会话存储

外部依赖（不运行在我们的服务器上）：

• vLLM — Qwen3.6-35B-A3B-FP8 运行在 vllm-fast.cxr-insight.com（通过 Cloudflare 隧道）
• Embedding 服务 — via OpenRouter（qwen/qwen3-embedding-8b，通过 LiteLLM 代理）
• S3 存储 — PVC 后端 zhiheng-user-data（无需外部 S3）
• Cloudflare — DNS + TLS 终结 + zhiheng.app 隧道

Git Worktree（工作树）设置

每位开发者在一个 git worktree（工作树）中工作——它与主仓库共享 git 对象，是轻量级的分支工作空间。

根仓库（生产）： /home/ubuntu/dev/GXNU/zhiheng/（分支 main）

你的工作树： /home/ubuntu/dev/GXNU/zhiheng-{你的名字}/

工作树的优势

• 节省磁盘 — 仅需数 MB，而每次完整克隆需要 ~100MB+
• 即时分支共享 — 所有工作树立即可见提交
• 并行开发 — 可同时操作多个分支，无需切换

创建你的开发环境

创建工作树：

按照 AGENTS.md 中的设置命令操作

设置过程会自动完成：

1. 在 /home/ubuntu/dev/GXNU/zhiheng-{name}/ 下创建工作树
2. 偏移端口（nginx、redis、lightrag、deerflow）避免冲突
3. 创建隔离的 Docker 网络 + 命名卷
4. 修复 LightRAG .env（被 *** 掩盖的值）
5. 在数据库中安装 Apache AGE 扩展
6. 配置 Cloudflare 隧道路由 + DNS 记录

你的实例访问地址

访问方式	URL / 端口
Web UI	https://{name}.zhiheng.app/
本地	http://localhost:{nginx-端口}/
Nginx 端口	每个工作树端口不同
LightRAG 端口	127.0.0.1:{lightrag-端口}

HTTP 基础认证： 用户名 admin / 密码（查看 .env）

Docker Compose 工作流

所有 Docker 命令应在你的工作树目录中执行：

cd /home/ubuntu/dev/GXNU/zhiheng-{你的名字}/

常用命令

# 完整重建 + 重启
docker compose up -d --build

# 仅前端（代码改动后）
docker compose build frontend && docker compose up -d --force-recreate frontend

# 仅后端（Python 改动后）
docker compose build backend && docker compose up -d --force-recreate backend

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f backend
docker compose logs -f lightrag

# 停止所有服务
docker compose down

⚠️ 关键 Docker 注意事项

1. docker compose restart 不会加载新镜像 — docker compose build 之后，必须用 stop + rm + create 或 up -d --force-recreate。

2. docker compose restart 不会重载 .env — 容器必须重建才能读取新环境变量。请使用 up -d 而非 restart。

3. docker-compose.override.yml 端口合并问题 — 覆盖文件会合并端口数组而非替换。请直接编辑 docker-compose.yml。

4. Nginx DNS 缓存 — 后端重启后，nginx 可能缓存了旧 IP。重启 nginx：docker compose restart nginx。

5. LightRAG .env 被掩盖 — 新建工作树会继承被 Docker 掩盖的 *** 值。设置时自动修复。

6. Apache AGE 缺失 — 新的数据库容器默认没有 AGE 扩展。设置时自动安装。

Cloudflare 隧道

我们的生产域名 zhiheng.app 通过 Cloudflare Tunnel（cloudflared）提供服务：

• 隧道： zhiheng-main（2c79c700）
• Systemd 服务： cloudflared-zhiheng-app.service
• 配置文件： /etc/cloudflared/zhiheng-app-tunnel.yml

每位团队成员的子域名（{name}.zhiheng.app）都通过同一隧道路由到各自的 nginx 端口。

错误码

错误码	含义	解决方法
1033	隧道连接未运行	sudo systemctl restart cloudflared-zhiheng-app.service
504	后端未响应（100秒超时）	检查后端日志：docker compose logs backend
530	源站 SSL/TLS 问题	检查 Cloudflare 隧道配置

安全规范 ⚠️

我们是在生产基础设施上开发。 每个改动都会影响真实用户。请遵守以下规范：

1. 不要暴露服务

• 所有服务绑定到 127.0.0.1 或 Docker 内部网络
• 只有 nginx（:8888）和团队成员的 nginx 端口对外开放
• Redis 和 LightRAG 端口仅限本地访问
• 绝对不要将数据库端口发布到宿主机

2. 保护凭证

.env 文件包含敏感信息：

• 数据库密码
• JWT 密钥
• API 密钥（vLLM、embedding、内部服务）
• Cloudflare 令牌

规则：

• ✅ .env 已在 .gitignore 中 — 绝不提交
• ❌ 绝不在聊天或文档中分享 .env 内容
• ❌ 绝不在源代码中硬编码密钥
• ✅ 使用环境变量

3. 先测试再部署

当你修改代码时：

1. 先在本地工作树构建
2. 测试你的子域名（{name}.zhiheng.app）
3. 然后才合并到 main 发布到生产

4. 数据库安全

• 每个工作树有独立的数据库 — 你不会意外影响他人
• 未经明确授权，不要连接生产数据库
• 执行破坏性操作前先备份

5. Cloudflare Workers

我们的认证由 Cloudflare Worker 处理（基于会话，非 Basic Auth 头）。未经团队协调，不要修改 Worker。

6. PVC 存储

所有工作树共用同一个 PVC（zhiheng-user-data-pvc）。通过 per-user subPath 挂载 — 不会发生跨用户数据泄露。

与 AI 智能体协作

DeerFlow 是我们的 AI 智能体平台——可通过聊天端点或前端聊天界面访问。

AI 智能体工作原理

• DeerFlow 作为 Kubernetes 部署运行
• 它有自定义工具用于 LightRAG 查询、课程管理和 PPT 生成
• 它使用技能（可复用流程）处理复杂工作流
• 聊天每次运行无状态 — 对话历史由后端维护

示例提示词

生成 PPT：

请为第十课《了解宪法》生成一份 PPT，
包含 5 张幻灯片，介绍中国宪法制度的要点。

查询知识库：

教科书关于"法治建设"在中学教育背景下的内容
是怎么描述的？

创建教案：

为八年级第四单元第二课创建教案，聚焦
"公民的基本权利和义务"。
包含教学目标、重点和课堂活动。

调试问题：

知识页面搜索"宪法"时返回空结果，
能帮我诊断问题吗？

通过飞书与 AI 交互

你也可以通过飞书群使用聊天界面获取帮助。

提示词技巧

1. 具体明确 — 包含课号、年级和具体主题
2. 提供上下文 — "八年级第四单元，教科书提到..."
3. 要求结构化 — "组织成 3 个部分，使用要点"
4. 迭代优化 — 如果第一次结果不理想，进一步细化提示词

故障排除

常见问题

问题	诊断	解决方法
前端显示旧代码	Vite hash 确定性	docker compose build --no-cache frontend && docker compose up -d --force-recreate frontend
重建后端后 502	Nginx 上游 IP 缓存	docker compose restart nginx
LightRAG 返回 0 结果	工作区未设置或为空	检查 docker-compose.yml 是否有 command: --workspace {name}
聊天卡住（504）	智能体超时或 ClientDisconnect	检查后端日志中的 ClientDisconnect 错误
无法登录	密码错误	admin / （查看 .env）
错误 1033	隧道未运行	sudo systemctl restart cloudflared-zhiheng-app.service
LightRAG 崩溃循环	.env 中有 *** 或缺少 AGE	修复 .env 或重新安装 AGE

获取帮助

1. 查看容器日志：docker compose logs -f {服务名}
2. 查看 Docker 状态：docker compose ps
3. 使用聊天界面或飞书
4. 查阅本文档的常见问题