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 从源码编译

# 克隆代码
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

# 构建镜像
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（推荐）

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:

启动：

# 创建环境变量文件
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 手动迁移

# 使用 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 基本配置

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 负载均衡配置

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：

[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

启用服务：

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

---

7. 监控与日志

7.1 日志配置

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

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

# 查看 Docker 日志
docker logs -f vbase_app_1

7.2 Prometheus 监控

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

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

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

7.3 健康检查

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

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

---

8. 备份与恢复

8.1 数据库备份

#!/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 数据库恢复

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

# PostgreSQL
psql -U postgres vbase < backup_file.sql

---

9. 故障排查

9.1 常见问题

服务无法启动

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

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

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

数据库连接失败

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

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

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

Redis 连接失败

# 测试 Redis 连接
redis-cli ping

# 检查 Redis 状态
redis-cli INFO server

9.2 性能调优

数据库优化

-- 添加索引
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 优化

# 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 平滑升级

# 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 回滚

# 停止服务
sudo systemctl stop vbase

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

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

# 启动服务
sudo systemctl start vbase