docs: 更新项目规范，标记审计修复完成状态

2026-06-28 13:13:03 +08:00
parent 996d193808
commit 1b32a6feef
1 changed files with 230 additions and 0 deletions
@@ -0,0 +1,230 @@
+# 小虾SaaS 项目规范
+
+> **最后更新：** 2026-06-28  
+> **维护者：** 灵应（主Agent）  
+> **所有Agent在执行任务前必须先阅读本文件**
+
+---
+
+## 一、项目概述
+
+- **项目名称：** 小虾SaaS (xiaoxia-saas)
+- **代码仓库：** https://git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas
+- **当前版本：** v0.1.66+
+- **活跃分支：** develop（开发）、main（生产）
+- **构建服务器：** 114.55.236.178（git.xiaoxiajianji.com）
+- **业务服务器：** 47.98.113.167（saas-api.xiaoxiajianji.com）
+- **生产域名：** https://saas.xiaoxiajianji.com
+
+---
+
+## 二、通用规则（所有Agent必须遵守）
+
+1. **所有回复使用中文**
+2. **代码提交只推送到 develop 分支**，不直接推main
+3. **Git提交配置：** 用户 CI Test，邮箱 ci-test@xiaoxia.com
+4. **每次操作前后记录验证结果**
+5. **修复完成后创建PR**，指向develop分支
+6. **不得删除或覆盖生产数据**
+7. **服务器操作通过CMD Agent API执行**，不尝试直接SSH
+
+---
+
+## 三、访问凭据
+
+### 3.1 Gitea API
+```bash
+# 获取文件内容
+curl -s "https://git.xiaoxiajianji.com/api/v1/repos/xiaoxia/xiaoxia-saas/contents/<path>?ref=main" \
+  -H "Authorization: token 1f8058d097e3942a9ed31c44382baf7f08311272"
+
+# 获取目录列表
+curl -s "https://git.xiaoxiajianji.com/api/v1/repos/xiaoxia/xiaoxia-saas/contents/<dir>?ref=main" \
+  -H "Authorization: token 1f8058d097e3942a9ed31c44382baf7f08311272"
+
+# 创建/更新文件（通过API）
+curl -s -X POST "https://git.xiaoxiajianji.com/api/v1/repos/xiaoxia/xiaoxia-saas/contents/<path>" \
+  -H "Authorization: token 1f8058d097e3942a9ed31c44382baf7f08311272" \
+  -H "Content-Type: application/json" \
+  -d '{"message":"commit msg","content":"base64内容","branch":"develop"}'
+```
+
+### 3.2 构建服务器 CMD Agent（114.55.236.178）
+```bash
+curl -s -m 30 -H "Authorization: xsa-899b1ae3d6300417c74f56d748849dc3" \
+  "https://git.xiaoxiajianji.com/cmd-agent/exec" \
+  -d '{"command":"你的命令"}'
+```
+- 代码目录：`/opt/xiaoxia-saas`
+- 备份目录：`/opt/backup/`
+- ⚠️ Token在服务重启时可能变化
+
+### 3.3 业务服务器 CMD Agent（47.98.113.167）
+```bash
+curl -s -m 30 -H "Authorization: xsa-f2778a6953d59948cd1e5be4d99f60f7" \
+  "https://saas-api.xiaoxiajianji.com/cmd-agent/exec" \
+  -d '{"command":"你的命令"}'
+```
+- 部署目录：`/opt/xiaoxia-saas/deploy/`
+- 备份目录：`/opt/backup/`
+- 健康检查：`/opt/health_check.sh`
+- ⚠️ Token在服务重启时可能变化
+
+---
+
+## 四、Agent 分工
+
+### 4.1 后端编程
+**职责：** Python后端代码修复和优化
+**负责模块：** apps/api/、apps/worker/、packages/
+
+**当前任务：**
+| # | 优先级 | 任务 | 文件 | 状态 |
+|---|--------|------|------|------|
+| B1 | P1 | auth.py forgot_password硬编码localhost→settings.APP_BASE_URL | apps/api/app/api/v1/auth.py:209 | ⏳ 待修复 |
+| B2 | P1 | generation.py直接创建DB连接→改为依赖注入 | apps/worker/video_processing/generation.py:139-179 | ⏳ 待修复 |
+| B3 | P2 | EditingMode枚举重复→统一到packages/domain | apps/worker/video_processing/editing_modes.py | ⏳ 待修复 |
+| B4 | P2 | SMTP_FRON_NAME拼写→SMTP_FROM_NAME | packages/config/settings.py | ⏳ 待修复 |
+| B5 | P2 | UserModel配额字段Float→Integer | packages/adapters/sqlalchemy_impl/models.py:27-28 | ⏳ 待修复 |
+| B6 | P2 | .env.production MAX_OVERFLOW=100→10 | .env.production:27 | ⏳ 待修复 |
+
+### 4.2 前端编码
+**职责：** 前端代码健康检查和修复
+**负责模块：** apps/web/
+
+**当前任务：**
+| # | 优先级 | 任务 | 状态 |
+|---|--------|------|------|
+| F1 | P1 | 验证package.json/tsconfig.json/vite.config.ts完整性 | ⏳ 待检查 |
+| F2 | P1 | 清理空文件和死代码（workspaceStore等） | ⏳ 待检查 |
+| F3 | P2 | TypeScript严格模式确认 | ⏳ 待检查 |
+| F4 | P2 | console.log残留清理 | ⏳ 待检查 |
+| F5 | P2 | 确认Vite+Next.js框架已统一 | ⏳ 待检查 |
+
+### 4.3 构建服务器运维
+**职责：** 构建服务器安全和基础设施维护
+**服务器：** 114.55.236.178
+
+**当前任务：**
+| # | 优先级 | 任务 | 状态 |
+|---|--------|------|------|
+| C1 | P0 | SSH关闭密码登录（PasswordAuthentication→no） | ✅ 已完成 |
+| C2 | P0 | Docker Registry启用认证 | ✅ 已完成 |
+| C3 | P1 | PermitRootLogin→no | ✅ 已完成 |
+| C4 | P1 | 关闭4个临时HTTP服务器（8888/9999/18080/18081） | ✅ 已完成 |
+| C5 | P1 | 端口8443/2222添加UFW规则 | ✅ 已完成 |
+| C6 | P2 | 修复备份脚本heredoc语法 | ✅ 已完成 |
+
+### 4.4 业务服务器运维
+**职责：** 业务服务器运维和监控
+**服务器：** 47.98.113.167
+
+**当前任务：**
+| # | 优先级 | 任务 | 状态 |
+|---|--------|------|------|
+| S1 | P1 | Grafana端口3003限制为内网 | ✅ 已完成 |
+| S2 | P1 | 排查不明进程（8080/8081端口） | ✅ 已完成 |
+| S3 | P1 | Grafana/Prometheus添加资源限制 | ✅ 已完成 |
+| S4 | P2 | 清理旧postgres容器 | ✅ 已完成 |
+| S5 | P1 | 评估内存状况（可用仅344Mi） | ✅ 已完成 |
+
+### 4.5 部署发布专家
+**职责：** CI/CD流水线和部署管理
+
+**当前任务：**
+| # | 优先级 | 任务 | 状态 |
+|---|--------|------|------|
+| D1 | P0 | .env.production从Git移除 | ⏳ 待修复 |
+| D2 | P2 | Worker容器内存限制评估（4GB偏高） | ✅ 已完成（PR#70） |
+| D3 | P1 | 检查Gitea Actions流水线状态 | ⏳ 待检查 |
+
+### 4.6 代码审计
+**职责：** 代码质量审计和复查
+**上次报告：** /audits/code-audit-report-v3.md
+
+### 4.7 安全审计
+**职责：** 基础设施安全审计
+**上次报告：** /审计报告/审计报告_基础设施与安全_20260628.md
+
+### 4.8 灵应（主Agent）
+**职责：** 任务协调、进度追踪、综合报告汇总
+
+---
+
+## 五、当前修复进度追踪
+
+> 每次修复完成后，对应Agent更新此表的状态列
+
+### P0 问题（必须立即处理）
+| # | 问题 | 负责Agent | 状态 | 完成时间 |
+|---|------|----------|------|----------|
+| P0-1 | .env.production在Git中 | 部署发布专家 | ⏳ | - |
+| P0-2 | Docker Registry无认证 | 构建服务器运维 | ✅ | 2026-06-28 |
+| P0-3 | 构建服务器SSH密码登录 | 构建服务器运维 | ✅ | 2026-06-28 |
+
+### P1 问题（48小时内处理）
+| # | 问题 | 负责Agent | 状态 | 完成时间 |
+|---|------|----------|------|----------|
+| P1-1 | auth.py硬编码localhost | 后端编程 | ⏳ | - |
+| P1-2 | generation.py直连DB | 后端编程 | ⏳ | - |
+| P1-3 | 临时HTTP服务器未关闭 | 构建服务器运维 | ✅ | 2026-06-28 |
+| P1-4 | 构建服务器PermitRootLogin | 构建服务器运维 | ✅ | 2026-06-28 |
+| P1-5 | 内存紧张(344Mi) | 业务服务器运维 | ✅ | 2026-06-28 |
+| P1-6 | Grafana/Prometheus无限制 | 业务服务器运维 | ✅ | 2026-06-28 |
+| P1-7 | 不明进程(8080/8081) | 业务服务器运维 | ✅ | 2026-06-28 |
+| P1-8 | Grafana端口3003暴露 | 业务服务器运维 | ✅ | 2026-06-28 |
+
+### P2 问题（一周内处理）
+| # | 问题 | 负责Agent | 状态 | 完成时间 |
+|---|------|----------|------|----------|
+| P2-1 | EditingMode枚举重复 | 后端编程 | ⏳ | - |
+| P2-2 | SMTP_FRON_NAME拼写 | 后端编程 | ⏳ | - |
+| P2-3 | MAX_OVERFLOW配置 | 后端编程 | ⏳ | - |
+| P2-4 | UserModel类型不一致 | 后端编程 | ⏳ | - |
+| P2-5 | 前端空文件/死代码 | 前端编码 | ⏳ | - |
+| P2-6 | 备份脚本heredoc | 构建服务器运维 | ✅ | 2026-06-28 |
+| P2-7 | Worker内存限制偏高 | 部署发布专家 | ✅ | 2026-06-28 |
+
+---
+
+## 六、项目结构
+
+```
+xiaoxia-saas/
+├── apps/
+│   ├── api/          ← 后端API服务（FastAPI）
+│   ├── web/          ← 前端（Vite/Next.js）
+│   └── worker/       ← 后台任务处理（Celery）
+├── packages/
+│   ├── domain/       ← 领域模型
+│   ├── config/       ← 配置管理
+│   ├── adapters/     ← 适配器层
+│   └── shared/       ← 公共模块
+├── deploy/           ← 部署配置
+│   └── docker-compose.production.yml
+├── alembic/          ← 数据库迁移
+├── .env.production   ← ⚠️ 待从Git移除
+└── .gitea/workflows/ ← CI/CD配置
+```
+
+---
+
+## 七、容器清单（业务服务器）
+
+| 容器名 | 端口 | 内存限制 | 状态 |
+|--------|------|---------|------|
+| xiaoxia-api-production | 8001→8000 | 2GB | ✅ |
+| xiaoxia-web-production | 3002→80 | 512MB | ✅ |
+| xiaoxia-worker-production | - | 2GB | ✅（已优化） |
+| xiaoxia-postgres-production | 127.0.0.1:5433→5432 | 1GB | ✅ |
+| xiaoxia-redis-production | 127.0.0.1:6380→6379 | 512MB | ✅ |
+| xiaoxia-grafana-production | 3003→3000 | 512MB | ✅（已添加） |
+| xiaoxia-prometheus-production | 127.0.0.1:9090→9090 | 256MB | ✅（已添加） |
+
+---
+
+## 八、下次审计
+
+- **时间：** 2026-07-05
+- **目标：** 综合评分达到 7/10
+- **复查重点：** 所有P0/P1问题是否已修复