# 小虾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/?ref=main" \ -H "Authorization: token 1f8058d097e3942a9ed31c44382baf7f08311272" # 获取目录列表 curl -s "https://git.xiaoxiajianji.com/api/v1/repos/xiaoxia/xiaoxia-saas/contents/?ref=main" \ -H "Authorization: token 1f8058d097e3942a9ed31c44382baf7f08311272" # 创建/更新文件（通过API） curl -s -X POST "https://git.xiaoxiajianji.com/api/v1/repos/xiaoxia/xiaoxia-saas/contents/" \ -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问题是否已修复