xiaoxia-saas/项目规范.md

小虾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

# 获取文件内容
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）

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）

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问题是否已修复