xiaoxia
1b32a6feef
CI/CD Pipeline / Validate Code Quality And Tests (push) Has been cancelled
CI/CD Pipeline / Frontend Lint (push) Has been cancelled
Deploy / Deploy Staging (push) Has been cancelled
Deploy / Build Production Runtime Images (push) Has been cancelled
Deploy / Deploy Production (push) Has been cancelled
Deploy / Production Browser E2E (push) Has been cancelled
230 lines
8.9 KiB
Markdown
230 lines
8.9 KiB
Markdown
# 小虾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问题是否已修复 |