[项目管理] 添加开发规范和任务管理文档
- 添加 Claude 项目开发指引 (.claude/project-instructions.md) - 添加开发记录文档 (docs/DEVELOPMENT.md) - 添加详细任务清单 (docs/TODO.md) - 添加部署配置文档 (docs/DEPLOYMENT.md) 包含：开发流程规范、任务追踪、Git工作流、部署指南
This commit is contained in:
huangzhenpc
357
docs/DEPLOYMENT.md
Normal file
357
docs/DEPLOYMENT.md
Normal 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
|
||||
Reference in New Issue
Block a user