OpenHub 部署指南

本文档介绍如何在不同环境中部署 OpenHub。

---

目录

• Docker 部署（推荐）
• 手动部署
• 生产环境配置
• 数据库迁移
• 健康检查
• 故障排查

---

Docker 部署（推荐）

前置要求

• Docker 20.10+
• Docker Compose 2.0+

快速开始

1. 克隆项目

git clone https://github.com/Grong/openhub.git
cd openhub

2. 配置环境变量

cp .env.example .env
# 编辑 .env，至少修改以下配置：
# - JWT_SECRET（必须修改）
# - BYOK_ENCRYPTION_KEY（必须修改）
# - LLM 供应商 API Keys

3. 启动服务

docker-compose up -d

4. 检查服务状态

docker-compose ps
docker-compose logs -f api

5. 访问服务

• API: http://localhost:6006
• 前端: http://localhost:6006
• 文档: http://localhost:5173

停止服务

docker-compose down

查看日志

# 查看所有日志
docker-compose logs -f

# 只查看 API 日志
docker-compose logs -f api

---

手动部署

前置要求

• Rust 1.91+
• SQLite 3.35+ 或 PostgreSQL 14+
• sqlx-cli

安装步骤

1. 安装 Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default nightly-2025-11-30

2. 安装 sqlx-cli

cargo install sqlx-cli --no-default-features --features sqlite

3. 克隆项目

git clone https://github.com/Grong/openhub.git
cd openhub

4. 配置环境变量

cp .env.example .env
# 编辑 .env 配置

5. 初始化数据库

# 创建数据库
sqlx database create

# 运行迁移
sqlx migrate run

6. 构建项目

# 开发模式
cargo build

# 生产模式
cargo build --release

7. 运行服务

# 开发模式
cargo run --bin openhub-api

# 生产模式
./target/release/openhub-api

---

生产环境配置

必须修改的配置

# .env

# 1. JWT 密钥（必须修改为强密钥）
JWT_SECRET=$(openssl rand -base64 32)

# 2. API Key 加密密钥（必须修改）
BYOK_ENCRYPTION_KEY=$(openssl rand -hex 32)

# 3. 数据库（推荐使用 PostgreSQL）
DATABASE_URL=postgresql://user:password@localhost/openhub

# 4. CORS（设置具体域名）
ALLOWED_ORIGINS=https://yourdomain.com

# 5. 日志级别（生产环境建议 info）
RUST_LOG=info,openhub_api=info

推荐配置

# 启用 ZDR（零数据保留）
ENABLE_ZDR_DEFAULT=true

# 启用 Redis 缓存
REDIS_ENABLED=true
REDIS_HOST=localhost
REDIS_PORT=6379

# 启用监控
METRICS_ENABLED=true
OTEL_ENABLED=true
OTEL_ENDPOINT=http://localhost:4317

使用 PostgreSQL

1. 安装 PostgreSQL

# Ubuntu/Debian
sudo apt-get install postgresql

# macOS
brew install postgresql

2. 创建数据库

sudo -u postgres psql
CREATE DATABASE openhub;
CREATE USER openhub_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE openhub TO openhub_user;
\q

3. 更新 .env

DATABASE_URL=postgresql://openhub_user:your_password@localhost/openhub

4. 运行迁移

sqlx migrate run

---

数据库迁移

查看迁移状态

sqlx migrate info

运行迁移

sqlx migrate run

回滚迁移

sqlx migrate revert

创建新迁移

sqlx migrate add <migration_name>

---

健康检查

API 健康检查

curl http://localhost:6006/api/health

数据库连接检查

# SQLite
sqlite3 data/openhub.db "SELECT 1;"

# PostgreSQL
psql -U openhub_user -d openhub -c "SELECT 1;"

---

反向代理配置

Nginx

server {
    listen 80;
    server_name api.yourdomain.com;

    location / {
        proxy_pass http://localhost:6006;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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_cache_bypass $http_upgrade;
    }
}

Caddy

api.yourdomain.com {
    reverse_proxy localhost:6006
}

---

系统服务配置

systemd

创建 /etc/systemd/system/openhub.service：

[Unit]
Description=OpenHub API Service
After=network.target

[Service]
Type=simple
User=openhub
WorkingDirectory=/opt/openhub
Environment="RUST_LOG=info"
EnvironmentFile=/opt/openhub/.env
ExecStart=/opt/openhub/target/release/openhub-api
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

启动服务：

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

---

故障排查

服务无法启动

1. 检查日志

# Docker
docker-compose logs api

# systemd
sudo journalctl -u openhub -f

2. 检查端口占用

sudo lsof -i :6006

3. 检查数据库连接

# 测试数据库连接
sqlx database create

数据库迁移失败

# 查看迁移状态
sqlx migrate info

# 强制重置（谨慎使用）
sqlx database drop
sqlx database create
sqlx migrate run

性能问题

1. 检查数据库连接池

# 增加连接池大小
DB_MAX_CONNECTIONS=20

2. 启用 Redis 缓存

REDIS_ENABLED=true

3. 检查慢查询

# 启用查询日志
RUST_LOG=sqlx=debug

---

监控和告警

Prometheus

在 prometheus.yml 中添加：

scrape_configs:
  - job_name: 'openhub'
    static_configs:
      - targets: ['localhost:6006']

Grafana

导入 OpenHub Dashboard（待提供）

---

备份和恢复

SQLite 备份

# 备份
sqlite3 data/openhub.db ".backup data/openhub_backup_$(date +%Y%m%d).db"

# 恢复
cp data/openhub_backup_20260313.db data/openhub.db

PostgreSQL 备份

# 备份
pg_dump -U openhub_user openhub > openhub_backup_$(date +%Y%m%d).sql

# 恢复
psql -U openhub_user openhub < openhub_backup_20260313.sql

---

安全建议

1. 使用强密钥（JWT_SECRET, BYOK_ENCRYPTION_KEY）
2. 启用 HTTPS（使用 Let's Encrypt）
3. 配置防火墙规则
4. 定期更新依赖
5. 启用 ZDR（零数据保留）
6. 定期备份数据库
7. 监控异常访问

---

性能优化

1. 使用 PostgreSQL 替代 SQLite
2. 启用 Redis 缓存
3. 增加数据库连接池
4. 使用 CDN 加速静态资源
5. 启用 gzip 压缩
6. 配置反向代理缓存

---

联系支持

• GitHub Issues: https://github.com/Grong/openhub/issues
• Email: support@openhub.cn
• 文档: https://docs.openhub.cn