OneAuth/doc/deployment.md

# VBase 部署指南

## 1. 环境要求

### 1.1 系统要求

| 组件 | 最低配置 | 推荐配置 |
|------|----------|----------|
| CPU | 1核 | 4核 |
| 内存 | 512MB | 2GB |
| 硬盘 | 1GB | 10GB |
| 网络 | 10Mbps | 100Mbps |

### 1.2 依赖服务

| 服务 | 版本 | 说明 |
|------|------|------|
| Go | 1.21+ | 运行环境 |
| MySQL | 5.7+ | 推荐 8.0 |
| PostgreSQL | 12+ | 可选 |
| Redis | 6.0+ | 缓存与会话 |

---

## 2. 安装步骤

### 2.1 从源码编译

```bash
# 克隆代码
git clone https://github.com/veypi/vbase.git
cd vbase

# 安装依赖
go mod download

# 编译
go build -o vbase-server ./cmd/server

# 运行
./vbase-server
```

### 2.2 使用 Docker

```bash
# 构建镜像
docker build -t vbase:latest .

# 运行
docker run -d \
  -p 8080:8080 \
  -e DB_TYPE=mysql \
  -e DB_DSN="root:password@tcp(mysql:3306)/vbase" \
  -e REDIS_ADDR="redis:6379" \
  -e JWT_SECRET="your-secret-key" \
  vbase:latest
```

### 2.3 Docker Compose（推荐）

```yaml
version: '3.8'

services:
  app:
    image: vbase:latest
    build: .
    ports:
      - "8080:8080"
    environment:
      - SERVER_HOST=0.0.0.0
      - SERVER_PORT=8080
      - DB_TYPE=mysql
      - DB_DSN=root:${DB_PASSWORD}@tcp(mysql:3306)/vbase?charset=utf8mb4&parseTime=True&loc=Local
      - REDIS_ENABLED=true
      - REDIS_ADDR=redis:6379
      - JWT_SECRET=${JWT_SECRET}
      - INIT_ADMIN_PASSWORD=${ADMIN_PASSWORD}
    depends_on:
      - mysql
      - redis
    restart: unless-stopped

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=${DB_PASSWORD}
      - MYSQL_DATABASE=vbase
    volumes:
      - mysql_data:/var/lib/mysql
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    restart: unless-stopped

volumes:
  mysql_data:
  redis_data:
```

启动：

```bash
# 创建环境变量文件
cat > .env << EOF
DB_PASSWORD=your-db-password
JWT_SECRET=your-jwt-secret-min-32-characters
ADMIN_PASSWORD=your-admin-password
EOF

# 启动服务
docker-compose up -d
```

---

## 3. 环境变量配置

### 3.1 服务配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| SERVER_HOST | 0.0.0.0 | 服务监听地址 |
| SERVER_PORT | 8080 | 服务端口 |
| SERVER_MODE | debug | 运行模式: debug/release |

### 3.2 数据库配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| DB_TYPE | mysql | 数据库类型: mysql/postgres/sqlite |
| DB_DSN | - | 数据库连接字符串 |
| DB_MAX_OPEN | 100 | 最大连接数 |
| DB_MAX_IDLE | 10 | 最大空闲连接 |

**MySQL DSN 格式:**
```
user:password@tcp(host:port)/dbname?charset=utf8mb4&parseTime=True&loc=Local
```

**PostgreSQL DSN 格式:**
```
host=localhost user=postgres password=secret dbname=vbase port=5432 sslmode=disable
```

**SQLite DSN 格式:**
```
./vbase.db
```

### 3.3 Redis 配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| REDIS_ENABLED | true | 是否启用 Redis |
| REDIS_ADDR | localhost:6379 | Redis 地址 |
| REDIS_PASSWORD | - | Redis 密码 |
| REDIS_DB | 0 | 数据库编号 |

### 3.4 JWT 配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| JWT_SECRET | - | JWT 签名密钥（最少32字符） |
| JWT_ACCESS_EXPIRY | 1h | Access Token 有效期 |
| JWT_REFRESH_EXPIRY | 720h | Refresh Token 有效期 |
| JWT_ISSUER | vbase | Token 签发者 |

### 3.5 安全配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| BCRYPT_COST | 12 | 密码哈希成本因子 |
| MAX_LOGIN_ATTEMPTS | 5 | 最大登录尝试次数 |
| CAPTCHA_ENABLED | true | 是否启用验证码 |

### 3.6 OAuth 配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| OAUTH_GOOGLE_ENABLED | false | 启用 Google 登录 |
| OAUTH_GOOGLE_CLIENT_ID | - | Google Client ID |
| OAUTH_GOOGLE_CLIENT_SECRET | - | Google Client Secret |
| OAUTH_GITHUB_ENABLED | false | 启用 GitHub 登录 |
| OAUTH_GITHUB_CLIENT_ID | - | GitHub Client ID |
| OAUTH_GITHUB_CLIENT_SECRET | - | GitHub Client Secret |
| OAUTH_WECHAT_ENABLED | false | 启用微信登录 |
| OAUTH_WECHAT_APP_ID | - | 微信 App ID |
| OAUTH_WECHAT_APP_SECRET | - | 微信 App Secret |

### 3.7 初始化配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| INIT_ADMIN_USERNAME | admin | 初始管理员用户名 |
| INIT_ADMIN_PASSWORD | - | 初始管理员密码（空则随机生成） |
| INIT_ADMIN_EMAIL | admin@example.com | 初始管理员邮箱 |

---

## 4. 数据库迁移

### 4.1 自动迁移

服务启动时会自动执行数据库迁移，创建所需表结构。

### 4.2 手动迁移

```bash
# 使用 migrate 工具
go install github.com/golang-migrate/migrate/v4/cmd/migrate@latest

# 创建迁移文件
migrate create -ext sql -dir migrations create_users_table

# 执行迁移
migrate -path migrations -database "mysql://user:password@tcp(localhost:3306)/vbase" up
```

---

## 5. Nginx 反向代理

### 5.1 基本配置

```nginx
upstream vbase {
    server 127.0.0.1:8080;
    keepalive 32;
}

server {
    listen 80;
    server_name iam.example.com;

    # 强制 HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name iam.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:50m;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # 日志
    access_log /var/log/nginx/vbase_access.log;
    error_log /var/log/nginx/vbase_error.log;

    location / {
        proxy_pass http://vbase;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 5s;
        proxy_send_timeout 10s;
        proxy_read_timeout 10s;
    }
}
```

### 5.2 负载均衡配置

```nginx
upstream vbase {
    least_conn;
    server 10.0.1.10:8080 weight=5;
    server 10.0.1.11:8080 weight=5;
    server 10.0.1.12:8080 backup;
    keepalive 32;
}
```

---

## 6. 系统服务

### 6.1 systemd 服务

创建 `/etc/systemd/system/vbase.service`：

```ini
[Unit]
Description=VBase IAM Service
After=network.target mysql.service redis.service

[Service]
Type=simple
User=vbase
Group=vbase
WorkingDirectory=/opt/vbase
ExecStart=/opt/vbase/vbase-server
Restart=always
RestartSec=5
Environment="SERVER_HOST=0.0.0.0"
Environment="SERVER_PORT=8080"
Environment="DB_TYPE=mysql"
Environment="DB_DSN=root:password@tcp(localhost:3306)/vbase"
Environment="JWT_SECRET=your-secret-key"

# 安全设置
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/vbase/logs

[Install]
WantedBy=multi-user.target
```

启用服务：

```bash
sudo systemctl daemon-reload
sudo systemctl enable vbase
sudo systemctl start vbase
sudo systemctl status vbase
```

---

## 7. 监控与日志

### 7.1 日志配置

日志输出到 stdout，使用 journald 或 docker 收集：

```bash
# 查看服务日志
sudo journalctl -u vbase -f

# 查看 Docker 日志
docker logs -f vbase_app_1
```

### 7.2 Prometheus 监控

添加 Prometheus 指标端点（需自行集成）：

```go
// 在 main.go 中添加
import "github.com/prometheus/client_golang/prometheus/promhttp"

r.Get("/metrics", promhttp.Handler())
```

### 7.3 健康检查

```bash
# 健康检查端点
curl http://localhost:8080/health

# 预期响应
{"code":200,"data":{"status":"ok","timestamp":"2024-01-01T00:00:00Z"}}
```

---

## 8. 备份与恢复

### 8.1 数据库备份

```bash
#!/bin/bash
# backup.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR=/backup/vbase

# MySQL
mysqldump -u root -p'password' vbase > $BACKUP_DIR/vbase_$DATE.sql

# PostgreSQL
pg_dump -U postgres vbase > $BACKUP_DIR/vbase_$DATE.sql

# 保留最近 7 天
cd $BACKUP_DIR && ls -t *.sql | tail -n +8 | xargs rm -f
```

### 8.2 数据库恢复

```bash
# MySQL
mysql -u root -p'password' vbase < backup_file.sql

# PostgreSQL
psql -U postgres vbase < backup_file.sql
```

---

## 9. 故障排查

### 9.1 常见问题

**服务无法启动**

```bash
# 检查端口占用
lsof -i :8080

# 检查环境变量
cat /opt/vbase/.env

# 查看详细错误日志
sudo journalctl -u vbase -n 100 --no-pager
```

**数据库连接失败**

```bash
# 测试数据库连接
mysql -u root -p -h localhost -e "SELECT 1"

# 检查网络连通性
telnet mysql-host 3306

# 检查用户权限
mysql> SHOW GRANTS FOR 'user'@'host';
```

**Redis 连接失败**

```bash
# 测试 Redis 连接
redis-cli ping

# 检查 Redis 状态
redis-cli INFO server
```

### 9.2 性能调优

**数据库优化**

```sql
-- 添加索引
ALTER TABLE users ADD INDEX idx_email (email);
ALTER TABLE org_members ADD INDEX idx_org_user (org_id, user_id);
ALTER TABLE oauth_tokens ADD INDEX idx_access_token (access_token);

-- 分析表
ANALYZE TABLE users, orgs, org_members;
```

**Redis 优化**

```conf
# redis.conf
maxmemory 256mb
maxmemory-policy allkeys-lru
save 900 1
save 300 10
save 60 10000
```

---

## 10. 安全加固

### 10.1 网络安全

- 使用防火墙限制访问：仅开放 80/443 端口
- 配置 fail2ban 防止暴力破解
- 使用 CloudFlare 等 CDN 防护 DDoS

### 10.2 应用安全

- 定期更换 JWT 密钥
- 启用验证码防止暴力破解
- 配置 CORS 白名单

### 10.3 数据安全

- 数据库密码复杂度要求
- 定期备份并加密存储
- 敏感操作记录审计日志

---

## 11. 升级指南

### 11.1 平滑升级

```bash
# 1. 拉取新版本
git pull origin main

# 2. 编译新版本
go build -o vbase-server-new ./cmd/server

# 3. 备份数据库
./backup.sh

# 4. 停止旧版本
sudo systemctl stop vbase

# 5. 替换二进制文件
mv vbase-server vbase-server-old
mv vbase-server-new vbase-server

# 6. 启动新版本
sudo systemctl start vbase

# 7. 验证服务
curl http://localhost:8080/health
```

### 11.2 回滚

```bash
# 停止服务
sudo systemctl stop vbase

# 恢复旧版本
mv vbase-server-old vbase-server

# 恢复数据库
mysql -u root -p vbase < backup_before_upgrade.sql

# 启动服务
sudo systemctl start vbase
```