# 部署配置文档

## 📦 部署架构

### 主系统部署

**环境要求：**
- 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