oadmin/relay-saas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[项目管理] 添加开发规范和任务管理文档
Some checks failed
CI / Unit tests (push) Has been cancelled
Details
CI / commit_lint (push) Has been cancelled
Details

Browse Source 
- 添加 Claude 项目开发指引 (.claude/project-instructions.md)
- 添加开发记录文档 (docs/DEVELOPMENT.md)
- 添加详细任务清单 (docs/TODO.md)
- 添加部署配置文档 (docs/DEPLOYMENT.md)

包含：开发流程规范、任务追踪、Git工作流、部署指南
This commit is contained in:
huangzhenpc
2025-12-29 23:02:49 +08:00
parent cb7c48bfa7
commit 91cbf92c13
4 changed files with 860 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
.claude/project-instructions.md Normal file
View File

@@ -0,0 +1,98 @@
# Relay-SaaS 项目开发指引
## 📌 项目概述
**项目名称：** Relay-SaaS（基于 one-api 的多租户 SaaS 系统）
**代码仓库：** https://git.586vip.cn/oadmin/relay-saas.git
**基础项目：** one-api (https://github.com/songquanpeng/one-api)
## 🎯 核心目标
构建一个多租户 API 中继 SaaS 平台：
- **主系统**：统一管理上游 API 渠道，集中计费
- **代理站点**：独立部署，服务终端用户
- **月套餐系统**：日/周/月额度限制的令牌系统
## 📋 重要提醒
### 开发原则
1. ⚠️ **保持可升级性**
- 新功能尽量创建新文件
- 避免大量修改核心代码
- 使用插件化架构
2. ⚠️ **每次开发前**
- 更新 `docs/DEVELOPMENT.md` 的开发记录
- 使用 TodoWrite 工具管理任务
- 在 Git commit 前确认修改内容
3. ⚠️ **提交代码时**
- 写清晰的 commit message
- 格式：`[模块] 功能描述`
- 例如：`[套餐系统] 添加日限额度检查逻辑`
4. ⚠️ **测试要求**
- 每个新功能必须手动测试
- 记录测试结果到开发文档
- 保证向后兼容
### 文件组织
**关键文档位置：**
- 📄 技术方案：`docs/SAAS-PLAN.md`
- 📝 开发记录：`docs/DEVELOPMENT.md`
- 📋 任务清单：`docs/TODO.md`
- 🔧 配置模板：`docs/DEPLOYMENT.md`
**代码组织：**
- 🆕 新增功能：`common/subscription/`, `model/agent_*.go`
- 🔧 扩展代码：在现有文件添加方法，不破坏原有逻辑
- 🧪 测试代码：`*_test.go` 文件
### Git 工作流
```bash
# 创建功能分支
git checkout -b feature/subscription-system
# 开发完成后提交
git add .
git commit -m "[套餐系统] 实现日/周/月额度限制"
# 推送到远程
git push origin feature/subscription-system
# 合并到 main
git checkout main
git merge feature/subscription-system
git push origin main
```
### 开发流程检查清单
- [ ] 确认需求，明确功能目标
- [ ] 更新 `docs/TODO.md` 任务状态
- [ ] 创建功能分支（可选）
- [ ] 编写代码，遵循现有风格
- [ ] 手动测试功能
- [ ] 更新 `docs/DEVELOPMENT.md` 记录
- [ ] 提交代码，写清晰的 message
- [ ] 推送到远程仓库
## 🔗 相关资源
- **Go 语言**：https://go.dev/doc/
- **Gin 框架**：https://gin-gonic.com/docs/
- **GORM**：https://gorm.io/docs/
- **One-API 文档**：项目 README.md
## 📞 联系方式
- **项目负责人**：huangzhenpc
- **Git 用户**：huangzhenpc
- **Git 仓库**：git.586vip.cn
---
**最后更新：** 2025-12-29
**文档版本：** v1.0

357
docs/DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,357 @@
# 部署配置文档
## 📦 部署架构
### 主系统部署
**环境要求：**
- Go 1.19+
- MySQL 8.0+ / PostgreSQL 13+
- Redis 6.0+
- 操作系统：Linux / macOS / Windows
**环境变量配置：**
```bash
# .env
# 数据库配置
SQL_DSN=root:password@tcp(localhost:3306)/oneapi_master
LOG_SQL_DSN=root:password@tcp(localhost:3306)/oneapi_logs # 可选
# Redis 配置
REDIS_CONN_STRING=redis://localhost:6379
SYNC_FREQUENCY=60 # 配置同步频率（秒）
# Session 密钥（重要：所有节点必须相同）
SESSION_SECRET=your_random_secret_here_change_it
# 节点类型
NODE_TYPE=master # 主节点
# 服务端口
PORT=3000
# 时区
TZ=Asia/Shanghai
# 日志目录
LOG_DIR=./logs
# 可选：批量更新
BATCH_UPDATE_ENABLED=true
BATCH_UPDATE_INTERVAL=5
# 可选：渠道自动测试
CHANNEL_TEST_FREQUENCY=1440 # 每天
CHANNEL_UPDATE_FREQUENCY=1440 # 每天
```
**Docker Compose 部署（推荐）：**
```yaml
version: '3.4'
services:
one-api-master:
image: relay-saas:latest
container_name: relay-saas-master
restart: always
ports:
- "3000:3000"
volumes:
- ./data:/data
- ./logs:/app/logs
environment:
- SQL_DSN=root:123456@tcp(db:3306)/oneapi_master
- REDIS_CONN_STRING=redis://redis:6379
- SESSION_SECRET=your_random_secret
- NODE_TYPE=master
- TZ=Asia/Shanghai
depends_on:
- db
- redis
redis:
image: redis:latest
container_name: relay-saas-redis
restart: always
db:
image: mysql:8.0
container_name: relay-saas-mysql
restart: always
ports:
- "3306:3306"
volumes:
- ./data/mysql:/var/lib/mysql
environment:
- MYSQL_ROOT_PASSWORD=123456
- MYSQL_DATABASE=oneapi_master
- TZ=Asia/Shanghai
```
---
### 代理站点部署
**环境变量配置：**
```bash
# .env
# 代理模式开关
AGENT_MODE=true
# 主系统地址
MASTER_SYSTEM_URL=https://master.example.com
# 代理站点 API Key（由主系统分配）
AGENT_SITE_API_KEY=ask-xxxxxxxxxxxxxxxx
# 本地数据库（独立）
SQL_DSN=root:password@tcp(localhost:3306)/oneapi_agent_001
# 本地 Redis（可选但推荐）
REDIS_CONN_STRING=redis://localhost:6379
SYNC_FREQUENCY=60
# Session 密钥（与主系统相同）
SESSION_SECRET=your_random_secret_here_change_it
# 服务端口
PORT=3000
# 时区
TZ=Asia/Shanghai
```
**Docker Compose 部署：**
```yaml
version: '3.4'
services:
one-api-agent:
image: relay-saas:latest
container_name: relay-saas-agent-001
restart: always
ports:
- "3000:3000"
volumes:
- ./data:/data
- ./logs:/app/logs
environment:
- AGENT_MODE=true
- MASTER_SYSTEM_URL=https://master.example.com
- AGENT_SITE_API_KEY=ask-xxxxxxxxxxxxxxxx
- SQL_DSN=root:123456@tcp(db:3306)/oneapi_agent
- REDIS_CONN_STRING=redis://redis:6379
- SESSION_SECRET=your_random_secret # 必须与主系统相同
- TZ=Asia/Shanghai
depends_on:
- db
- redis
redis:
image: redis:latest
container_name: relay-saas-agent-redis
restart: always
db:
image: mysql:8.0
container_name: relay-saas-agent-mysql
restart: always
volumes:
- ./data/mysql:/var/lib/mysql
environment:
- MYSQL_ROOT_PASSWORD=123456
- MYSQL_DATABASE=oneapi_agent
- TZ=Asia/Shanghai
```
---
## 🚀 部署步骤
### 1. 主系统部署
```bash
# 1. 克隆代码
git clone https://git.586vip.cn/oadmin/relay-saas.git
cd relay-saas
# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，设置 NODE_TYPE=master
# 3. 构建镜像（可选，如果不用官方镜像）
docker build -t relay-saas:latest .
# 4. 启动服务
docker-compose up -d
# 5. 查看日志
docker-compose logs -f
# 6. 访问系统
# http://localhost:3000
# 默认账号：root / 123456
```
### 2. 代理站点部署
```bash
# 1. 在主系统中创建代理站点
# 登录主系统 → 代理管理 → 添加站点 → 获取 API Key
# 2. 克隆代码到新服务器
git clone https://git.586vip.cn/oadmin/relay-saas.git
cd relay-saas
# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 文件：
# - AGENT_MODE=true
# - MASTER_SYSTEM_URL=主系统地址
# - AGENT_SITE_API_KEY=从主系统获取的密钥
# - SQL_DSN=独立的数据库连接
# 4. 启动服务
docker-compose up -d
# 5. 验证连接
curl http://localhost:3000/api/status
```
---
## 🔧 配置说明
### 重要配置项
#### SESSION_SECRET
- **作用**：用于加密 session 数据
- **要求**：主系统和所有代理站点必须使用相同的值
- **生成**：使用 `openssl rand -hex 32` 生成随机字符串
#### AGENT_SITE_API_KEY
- **格式**：`ask-` 前缀 + 48位随机字符
- **获取**：在主系统中创建代理站点时自动生成
- **安全**：定期轮换，不要泄露
#### SQL_DSN
- **主系统**：连接主数据库
- **代理站点**：连接独立数据库（不同实例）
- **格式**：
- MySQL: `user:password@tcp(host:port)/dbname`
- PostgreSQL: `postgres://user:password@host:port/dbname`
---
## 🔒 安全建议
### 网络安全
1. 使用 HTTPS（配置 Nginx 反向代理 + SSL）
2. 限制数据库访问（仅允许本地或内网）
3. 配置防火墙规则
4. 使用 VPN 或专线连接主从系统
### 应用安全
1. 定期更新密钥
2. 启用请求频率限制
3. 配置 IP 白名单
4. 监控异常请求
### 数据安全
1. 定期备份数据库
2. 加密敏感配置
3. 日志脱敏处理
4. 定期安全审计
---
## 📊 监控和运维
### 日志位置
- 应用日志：`./logs/`
- 访问日志：`./logs/access.log`
- 错误日志：`./logs/error.log`
### 健康检查
```bash
# 检查服务状态
curl http://localhost:3000/api/status
# 检查数据库连接
docker-compose exec one-api-master ./one-api --version
```
### 性能监控
- CPU 使用率：`docker stats`
- 内存使用：`docker stats`
- 数据库连接数：MySQL `SHOW PROCESSLIST;`
- Redis 状态：`redis-cli INFO`
### 常见问题
**1. 服务无法启动**
- 检查端口是否被占用：`netstat -tuln | grep 3000`
- 查看日志：`docker-compose logs`
**2. 数据库连接失败**
- 检查 SQL_DSN 配置
- 验证数据库是否启动：`docker-compose ps`
**3. 代理站点无法连接主系统**
- 检查 MASTER_SYSTEM_URL 是否正确
- 验证 AGENT_SITE_API_KEY 是否有效
- 检查网络连通性：`curl https://master.example.com/api/status`
---
## 🔄 更新和回滚
### 更新步骤
```bash
# 1. 拉取最新代码
git pull origin main
# 2. 停止服务
docker-compose down
# 3. 备份数据库
mysqldump -u root -p oneapi_master > backup.sql
# 4. 重新构建（如需要）
docker-compose build
# 5. 启动服务
docker-compose up -d
# 6. 检查日志
docker-compose logs -f
```
### 回滚步骤
```bash
# 1. 停止服务
docker-compose down
# 2. 切换到旧版本
git checkout <commit-hash>
# 3. 恢复数据库（如需要）
mysql -u root -p oneapi_master < backup.sql
# 4. 启动服务
docker-compose up -d
```
---
## 📞 支持
- **问题反馈**：Git Issues
- **文档更新**：提交 PR 到 `docs/` 目录
---
**最后更新**：2025-12-29
**文档版本**：v1.0

121
docs/DEVELOPMENT.md Normal file
View File

@@ -0,0 +1,121 @@
# 开发记录
## 项目信息
- **项目名称**：Relay-SaaS
- **基于项目**：one-api
- **开始日期**：2025-12-29
- **Git 仓库**：https://git.586vip.cn/oadmin/relay-saas.git
---
## 开发日志
### 2025-12-29
#### 项目初始化 ✅
**时间**：下午
**完成内容：**
1. 克隆 one-api 原始项目到本地
2. 深入探索代码结构：
- 令牌管理系统
- 额度计费系统
- 多机部署架构
3. 明确需求和技术方案
4. 编写详细的技术方案文档（`docs/SAAS-PLAN.md`）
5. Git 仓库初始化和首次提交
**技术方案要点：**
- 采用完全独立部署架构
- 主系统统一管理渠道
- 月套餐令牌系统（日/周/月限额）
- 插件化开发保持可升级性
**Git 记录：**
```
cb7c48b - first commit: one-api base code + SAAS plan document
```
**配置完成：**
- ✅ WSL sudo 免密配置
- ✅ Git 用户配置
- ✅ Git 凭据存储
- ✅ 项目 Claude 配置
**下一步计划：**
- Phase 1: 基础架构开发（代理站点表和模型）
- 搭建开发环境（Docker）
---
## 待解决问题
### 环境问题
- [ ] WSL 网络代理配置（如需访问外网）
- [ ] Docker 安装（用于运行 one-api）
### 技术问题
- [ ] 确定主从通信的认证机制细节
- [ ] 套餐额度重置的时区处理
---
## 技术笔记
### One-API 核心架构理解
**Token 验证流程：**
```
请求 → TokenAuth中间件 → ValidateUserToken →
检查状态/额度/IP/模型 → 通过
```
**计费流程：**
```
预扣费 → 调用上游API → 后结算（多退少补）
```
**关键文件：**
- `model/token.go` - Token模型和验证
- `relay/billing/billing.go` - 计费核心
- `middleware/auth.go` - 认证中间件
- `middleware/distributor.go` - 渠道分配
---
## 代码修改记录
### 本次开发周期：初始化
**新增文件：**
- `docs/SAAS-PLAN.md` - 完整技术方案文档
- `docs/DEVELOPMENT.md` - 本文件
- `docs/TODO.md` - 任务清单
- `.claude/project-instructions.md` - 项目开发指引
**修改文件：**
- 无
---
## 性能和优化记录
暂无
---
## Bug 记录
暂无
---
## 测试记录
暂无（项目初始阶段）
---
**文档维护**：每次开发完成后更新此文档
**最后更新**：2025-12-29

284
docs/TODO.md Normal file
View File

@@ -0,0 +1,284 @@
# 项目任务清单
> 本文档记录项目的所有开发任务和进度
---
## 📊 总体进度
- **Phase 1 - 基础架构**：0% (0/4)
- **Phase 2 - 套餐系统**：0% (0/4)
- **Phase 3 - 计费系统**：0% (0/4)
- **Phase 4 - 前端界面**：0% (0/4)
- **Phase 5 - 测试优化**：0% (0/4)
**总进度：** 0% (0/20)
---
## 🎯 Phase 1: 基础架构（预计2周）
### 1.1 数据库设计与实现
- [ ] 创建 `agent_sites` 表结构
- [ ] 创建 `agent_billing_logs` 表结构
- [ ] 编写数据库迁移脚本
- [ ] 测试表创建和索引
**优先级**：🔴 高
**预计工时**：2天
**负责人**：待分配
### 1.2 代理站点模型开发
- [ ] 创建 `model/agent_site.go`
- [ ] 实现 AgentSite 结构体
- [ ] 实现 CRUD 方法
- [ ] 实现站点 API Key 生成逻辑
**优先级**：🔴 高
**预计工时**：1天
**负责人**：待分配
**依赖**：1.1 完成
### 1.3 主系统代理中继接口
- [ ] 创建 `controller/agent_relay.go`
- [ ] 实现站点身份验证
- [ ] 实现额度检查逻辑
- [ ] 实现请求转发到上游渠道
- [ ] 添加路由配置
**优先级**：🔴 高
**预计工时**：3天
**负责人**：待分配
**依赖**：1.2 完成
### 1.4 代理站点转发逻辑
- [ ] 创建 `relay/proxy/master_proxy.go`
- [ ] 实现请求拦截
- [ ] 实现转发到主系统
- [ ] 添加重试和错误处理
- [ ] 配置环境变量支持
**优先级**：🔴 高
**预计工时**：2天
**负责人**：待分配
**依赖**：1.3 完成
---
## 🎯 Phase 2: 套餐系统（预计2周）
### 2.1 Token 表扩展
- [ ] 添加套餐相关字段到 tokens 表
- [ ] 编写数据库迁移脚本
- [ ] 更新 Token 模型结构体
- [ ] 测试字段添加
**优先级**：🟡 中
**预计工时**：1天
**负责人**：待分配
### 2.2 套餐定义和管理
- [ ] 创建 `common/subscription/plans.go`
- [ ] 定义套餐结构体和常量
- [ ] 实现套餐配置加载
- [ ] 创建套餐管理 API 接口
**优先级**：🟡 中
**预计工时**：2天
**负责人**：待分配
**依赖**：2.1 完成
### 2.3 额度检查逻辑
- [ ] 创建 `common/subscription/quota.go`
- [ ] 实现日/周/月额度检查
- [ ] 实现时间重置逻辑
- [ ] 添加到 TokenAuth 中间件
- [ ] 单元测试
**优先级**：🔴 高
**预计工时**：3天
**负责人**：待分配
**依赖**：2.2 完成
### 2.4 自动重置机制
- [ ] 创建定时任务
- [ ] 实现日重置（每日0点）
- [ ] 实现周重置（每周一）
- [ ] 实现月重置（每月1日）
- [ ] 测试跨时区场景
**优先级**：🟡 中
**预计工时**：2天
**负责人**：待分配
**依赖**：2.3 完成
---
## 🎯 Phase 3: 计费系统（预计2周）
### 3.1 代理计费日志表
- [ ] 完善 `agent_billing_logs` 表设计
- [ ] 创建日志模型 `model/agent_billing.go`
- [ ] 实现日志写入方法
- [ ] 添加索引优化查询
**优先级**：🔴 高
**预计工时**：1天
**负责人**：待分配
### 3.2 主系统计费记录
- [ ] 在 agent_relay 中添加计费逻辑
- [ ] 扣除代理站点额度
- [ ] 记录到 agent_billing_logs
- [ ] 实现异步批量写入
**优先级**：🔴 高
**预计工时**：3天
**负责人**：待分配
**依赖**：3.1 完成
### 3.3 额度同步机制
- [ ] 实现代理站点额度查询 API
- [ ] 实现额度同步定时任务
- [ ] 添加 Redis 缓存
- [ ] 测试高并发场景
**优先级**：🟡 中
**预计工时**：2天
**负责人**：待分配
**依赖**：3.2 完成
### 3.4 统计报表接口
- [ ] 创建 `controller/agent_stats.go`
- [ ] 实现代理站点消费统计
- [ ] 实现渠道使用统计
- [ ] 实现时间范围查询
**优先级**：🟢 低
**预计工时**：2天
**负责人**：待分配
**依赖**：3.3 完成
---
## 🎯 Phase 4: 前端界面（预计2周）
### 4.1 代理站点管理页面
- [ ] 创建代理站点列表页面
- [ ] 实现添加/编辑/删除功能
- [ ] 显示额度使用情况
- [ ] API Key 管理
**优先级**：🟡 中
**预计工时**：3天
**负责人**：待分配
### 4.2 套餐令牌管理页面
- [ ] 扩展令牌创建表单
- [ ] 添加套餐选择组件
- [ ] 显示日/周/月使用情况
- [ ] 额度预警提示
**优先级**：🟡 中
**预计工时**：3天
**负责人**：待分配
**依赖**：4.1 完成
### 4.3 计费统计报表页面
- [ ] 创建统计报表页面
- [ ] 实现图表展示（ECharts）
- [ ] 添加时间范围筛选
- [ ] 导出报表功能
**优先级**：🟢 低
**预计工时**：3天
**负责人**：待分配
**依赖**：4.2 完成
### 4.4 用户体验优化
- [ ] 添加加载状态
- [ ] 优化错误提示
- [ ] 响应式布局调整
- [ ] 多语言支持
**优先级**：🟢 低
**预计工时**：2天
**负责人**：待分配
**依赖**：4.3 完成
---
## 🎯 Phase 5: 测试优化（预计2周）
### 5.1 功能测试
- [ ] 编写单元测试
- [ ] 集成测试
- [ ] 端到端测试
- [ ] 测试覆盖率 > 60%
**优先级**：🔴 高
**预计工时**：3天
**负责人**：待分配
### 5.2 压力测试
- [ ] 准备测试数据
- [ ] 并发请求测试（1000 req/s）
- [ ] 数据库性能测试
- [ ] 内存和 CPU 监控
**优先级**：🟡 中
**预计工时**：2天
**负责人**：待分配
**依赖**：5.1 完成
### 5.3 安全加固
- [ ] SQL 注入防护测试
- [ ] XSS 防护测试
- [ ] API Key 安全审计
- [ ] 敏感数据加密
**优先级**：🔴 高
**预计工时**：2天
**负责人**：待分配
**依赖**：5.2 完成
### 5.4 文档完善
- [ ] API 接口文档
- [ ] 部署文档
- [ ] 用户使用手册
- [ ] 运维手册
**优先级**：🟡 中
**预计工时**：2天
**负责人**：待分配
**依赖**：5.3 完成
---
## 🚧 Bug 修复
> 开发过程中发现的 Bug 记录在此
暂无
---
## 💡 功能优化
> 非必需但可以改进的功能
暂无
---
## 📝 备注
- 每个任务完成后更新此文档
- 使用 `[x]` 标记已完成任务
- 优先级：🔴 高 / 🟡 中 / 🟢 低
- 预计工时仅供参考，实际可能有偏差
---
**最后更新**：2025-12-29
**文档版本**：v1.0