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