|
|
# 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
|
|
|
```
|