OpeniLinkOpeniLink
Hub 平台

部署指南

一键安装、Docker、系统服务等多种方式部署 OpeniLink Hub。

OpeniLink Hub 提供多种部署方式，从一键安装到容器化部署，满足不同场景的需求。

一键安装（推荐）

使用官方安装脚本，一行命令即可完成安装：

curl -fsSL https://raw.githubusercontent.com/openilink/openilink-hub/main/install.sh | sh

安装完成后，直接运行：

oih

一键安装默认使用 SQLite 作为数据库，零配置即可启动，无需额外安装任何依赖。

支持平台

操作系统架构支持情况
Linuxamd64✅ 支持
Linuxarm64✅ 支持
macOSamd64 (Intel)✅ 支持
macOSarm64 (Apple Silicon)✅ 支持

数据存储路径

安装后，SQLite 数据库文件存储在以下位置：

~/.local/share/openilink-hub/openilink.db
~/Library/Application Support/openilink-hub/openilink.db
/var/lib/openilink-hub/openilink.db

系统服务注册

通过 oih 内置命令，可以将 OpeniLink Hub 注册为系统服务，实现开机自启动：

# 注册为系统服务（Linux 使用 systemd，macOS 使用 launchd）
oih install

# 卸载系统服务
oih uninstall

Linux 系统使用 systemd 管理服务，macOS 系统使用 launchd 管理服务。注册后服务将在系统启动时自动运行。

Docker 单容器

如果你只需要快速启动一个实例，可以使用 Docker 单容器部署：

docker run -d \
  --name openilink-hub \
  -p 9800:9800 \
  ghcr.io/openilink/openilink-hub:latest

挂载数据卷以持久化数据：

docker run -d \
  --name openilink-hub \
  -p 9800:9800 \
  -v openilink_data:/var/lib/openilink-hub \
  ghcr.io/openilink/openilink-hub:latest

Docker Compose（生产环境）

生产环境推荐使用 Docker Compose，可以同时部署 PostgreSQL 和 MinIO 等依赖服务。

前置要求

  • Docker 20.10+
  • Docker Compose v2+
  • 至少 1GB 可用内存

克隆并启动

git clone https://github.com/openilink/openilink-hub.git
cd openilink-hub
docker compose up -d

服务组成

Docker Compose 配置包含三个服务：

1. PostgreSQL 17

# 数据库服务
postgres:
  image: postgres:17-alpine
  environment:
    POSTGRES_USER: openilink
    POSTGRES_PASSWORD: ${PASSWORD:-openilink}
    POSTGRES_DB: openilink
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U openilink -d openilink"]
    interval: 5s
    timeout: 5s
    retries: 10
  volumes:
    - pgdata:/var/lib/postgresql/data
  • 默认不暴露端口到宿主机，需要时可通过 docker compose exec postgres psql -U openilink 连接
  • 默认用户名/密码：openilink / openilink（可通过 PASSWORD 环境变量统一修改）
  • 数据持久化到 Docker Volume

2. MinIO 对象存储

# 对象存储服务
minio:
  image: minio/minio
  command: server /data --console-address ":9001"
  environment:
    MINIO_ROOT_USER: openilink
    MINIO_ROOT_PASSWORD: ${PASSWORD:-openilink}
  volumes:
    - miniodata:/data
  • 默认不暴露端口到宿主机，Hub 通过内部网络 minio:9000 访问
  • 默认用户名/密码：openilink / openilink（可通过 PASSWORD 环境变量统一修改）
# Hub 主服务
hub:
  build: .
  restart: on-failure
  ports:
    - "${HUB_PORT:-9800}:9800"
  environment:
    DATABASE_URL: postgres://openilink:${PASSWORD:-openilink}@postgres:5432/openilink?sslmode=disable
    RP_ORIGIN: ${RP_ORIGIN:-http://localhost:${HUB_PORT:-9800}}
    RP_ID: ${RP_ID:-localhost}
    STORAGE_ENDPOINT: minio:9000
    STORAGE_ACCESS_KEY: openilink
    STORAGE_SECRET_KEY: ${PASSWORD:-openilink}
    STORAGE_BUCKET: openilink
  depends_on:
    postgres:
      condition: service_healthy
    minio:
      condition: service_started

从源码构建

如果你需要自定义构建或参与开发，可以从源码编译：

# 克隆仓库
git clone https://github.com/openilink/openilink-hub.git
cd openilink-hub

# 构建（需要 Go 1.25+）
go build -o oih .

# 运行
./oih

从源码构建需要安装 Go 1.25 或更高版本。请确保 GOPATH 和 GOBIN 已正确配置。

CLI 命令

OpeniLink Hub 提供以下 CLI 命令：

命令说明
oih启动 OpeniLink Hub 服务
oih install注册为系统服务（Linux systemd / macOS launchd）
oih uninstall卸载系统服务
oih version查看当前版本信息

数据存储说明

OpeniLink Hub 默认使用 SQLite 作为数据库，零配置即可运行，适合个人使用和小团队场景。

如需切换到 PostgreSQL（推荐生产环境使用），只需设置 DATABASE_URL 环境变量：

# 使用 PostgreSQL
DATABASE_URL=postgres://user:password@host:5432/dbname?sslmode=disable

当未设置 DATABASE_URL 或其值不以 postgres:// 开头时，OpeniLink Hub 将自动使用 SQLite，数据存储在上文所述的默认路径中。

完整环境变量

以下是 OpeniLink Hub 支持的全部环境变量：

基础配置

变量默认值说明
LISTEN:9800HTTP 监听地址，格式为 :端口 或 地址:端口
DATABASE_URL—数据库连接字符串，不设置则默认使用 SQLite
SECRETchange-me-in-production服务端密钥，用于 Session 签名和数据加密

WebAuthn 配置

变量默认值说明
RP_ORIGINhttp://localhost:9800WebAuthn Relying Party 源地址，需与用户访问的 URL 一致
RP_IDlocalhostWebAuthn Relying Party ID，通常为域名（不含端口）

对象存储配置

变量默认值说明
STORAGE_ENDPOINT—MinIO/S3 兼容存储的端点地址
STORAGE_ACCESS_KEY—存储访问密钥
STORAGE_SECRET_KEY—存储密钥
STORAGE_BUCKETopenilink存储桶名称

OAuth 配置

变量默认值说明
GITHUB_CLIENT_ID—GitHub OAuth App 的 Client ID
GITHUB_CLIENT_SECRET—GitHub OAuth App 的 Client Secret
LINUXDO_CLIENT_ID—LinuxDo OAuth App 的 Client ID
LINUXDO_CLIENT_SECRET—LinuxDo OAuth App 的 Client Secret

AI 配置（全局）

变量默认值说明
AI_BASE_URL—OpenAI 兼容 API 的基础 URL
AI_API_KEY—AI API 的密钥
AI_MODEL—使用的模型名称（如 gpt-4、claude-3-sonnet 等）

生产环境注意事项

以下配置在生产环境中必须修改，否则将存在安全风险。

1. 修改 SECRET

SECRET 用于 Session 签名和敏感数据加密。生产环境务必设置为随机的强密码字符串：

# 生成随机密钥
openssl rand -hex 32

2. 配置 RP_ORIGIN 和 RP_ID

Passkey (WebAuthn) 认证要求 RP_ORIGIN 和 RP_ID 与用户实际访问的域名一致：

# 如果你的域名是 hub.example.com
RP_ORIGIN=https://hub.example.com
RP_ID=hub.example.com

RP_ORIGIN 必须包含协议（https://），RP_ID 只需要域名部分。如果配置不匹配，Passkey 注册和登录将失败。

3. 配置 SSL

生产环境建议使用反向代理（如 Nginx、Caddy）配置 HTTPS：

server {
    listen 443 ssl;
    server_name hub.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:9800;
        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;

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

4. 数据库安全

  • 修改 PostgreSQL 的默认密码
  • 限制数据库端口的网络访问
  • 定期备份数据库

配置 OAuth 提供者

GitHub OAuth

  1. 在 GitHub 上创建 OAuth App：Settings > Developer settings > OAuth Apps
  2. 设置 Authorization callback URL 为 https://你的域名/api/auth/callback/github
  3. 配置环境变量：
GITHUB_CLIENT_ID=你的_client_id
GITHUB_CLIENT_SECRET=你的_client_secret

LinuxDo OAuth

  1. 在 LinuxDo 开发者设置中创建 OAuth 应用
  2. 设置回调 URL 为 https://你的域名/api/auth/callback/linuxdo
  3. 配置环境变量：
LINUXDO_CLIENT_ID=你的_client_id
LINUXDO_CLIENT_SECRET=你的_client_secret

配置全局 AI

管理员可以在 Hub 中配置全局 AI 设置，使所有 Channel 都能使用 AI 自动回复功能：

  1. 使用管理员账号登录 Hub
  2. 进入管理面板的 AI 配置页面
  3. 设置 OpenAI 兼容 API 的参数：
    • Base URL：API 端点地址（如 https://api.openai.com/v1）
    • API Key：API 密钥
    • Model：模型名称（如 gpt-4）

或者通过环境变量配置：

AI_BASE_URL=https://api.openai.com/v1
AI_API_KEY=sk-xxxxx
AI_MODEL=gpt-4

全局 AI 配置后，每个 Channel 可以选择使用全局配置（source: "builtin"）或自定义配置（source: "custom"）。

数据库自动迁移

OpeniLink Hub 在每次启动时会自动检测并执行数据库迁移：

  • 首次启动时自动创建所有表结构
  • 版本升级时自动应用新的 schema 变更
  • 迁移过程是幂等的，重复执行不会产生副作用
  • 无需手动运行任何迁移命令

如果需要查看迁移日志，可以通过以下命令查看：

docker compose logs hub
journalctl -u openilink-hub
# 查看 launchd 服务日志
log show --predicate 'processImagePath contains "oih"' --last 1h

下一步

Hub 概览

OpeniLink Hub 是微信 Bot 消息管理的核心平台，提供多 Bot 管理、三通道分发和完善的控制台。

WebSocket 接入

通过 WebSocket 实时接收和发送微信消息，毫秒级延迟。

On this page

一键安装（推荐）支持平台数据存储路径系统服务注册Docker 单容器Docker Compose（生产环境）前置要求克隆并启动服务组成1. PostgreSQL 172. MinIO 对象存储3. OpeniLink Hub从源码构建CLI 命令数据存储说明完整环境变量基础配置WebAuthn 配置对象存储配置OAuth 配置AI 配置（全局）生产环境注意事项1. 修改 SECRET2. 配置 RP_ORIGIN 和 RP_ID3. 配置 SSL4. 数据库安全配置 OAuth 提供者GitHub OAuthLinuxDo OAuth配置全局 AI数据库自动迁移下一步