91cbf92c13
- 添加 Claude 项目开发指引 (.claude/project-instructions.md) - 添加开发记录文档 (docs/DEVELOPMENT.md) - 添加详细任务清单 (docs/TODO.md) - 添加部署配置文档 (docs/DEPLOYMENT.md) 包含：开发流程规范、任务追踪、Git工作流、部署指南
358 lines
7.1 KiB
Markdown
358 lines
7.1 KiB
Markdown
# 部署配置文档
|
||
|
||
## 📦 部署架构
|
||
|
||
### 主系统部署
|
||
|
||
**环境要求：**
|
||
- 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
|