Docker部署#

在官方GitHub仓库中，为我们提供了docker-compose.yml和.env.example文件，首先来看compose：

1
name: ${COMPOSE_PROJECT_NAME:-claude-code-hub}
2

3
services:
4
  postgres:
5
    image: postgres:18
6
    restart: unless-stopped
7
    # 不对外暴露数据库端口，仅允许容器内部网络访问
8
    # 如需调试，可取消注释下行（仅绑定本机）：
9
    # ports:
10
    #   - "127.0.0.1:35432:5432"
11
    env_file:
12
      - ./.env
13
    environment:
14
      POSTGRES_USER: ${DB_USER:-postgres}
15
      POSTGRES_PASSWORD: ${DB_PASSWORD:-postgres}
16
      POSTGRES_DB: ${DB_NAME:-claude_code_hub}
17
      # 使用自定义数据目录
18
      PGDATA: /data/pgdata
19
      # 设置时区为上海
20
      TZ: Asia/Shanghai
21
      PGTZ: Asia/Shanghai
22
    volumes:
23
      # 持久化数据库数据到本地 ./data/postgres 目录
24
      # 挂载到 /data 而不是 /var/lib/postgresql/data 避免权限冲突
25
      - ./data/postgres:/data
26
    healthcheck:
27
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-postgres} -d ${DB_NAME:-claude_code_hub}"]
28
      interval: 5s
29
      timeout: 5s
30
      retries: 10
31
      start_period: 10s
32

33
  redis:
34
    image: redis:7-alpine
35
    restart: unless-stopped
36
    volumes:
37
      # 持久化 Redis 数据到本地 ./data/redis 目录
38
      # 使用 AOF 持久化模式,确保数据不丢失
39
      - ./data/redis:/data
40
    command: redis-server --appendonly yes
41
    healthcheck:
42
      test: ["CMD", "redis-cli", "ping"]
43
      interval: 5s
44
      timeout: 3s
45
      retries: 5
46
      start_period: 5s
47

48
  app:
49
    image: ghcr.io/ding113/claude-code-hub:latest
50
    depends_on:
51
      postgres:
52
        condition: service_healthy
53
      redis:
54
        condition: service_healthy
55
    env_file:
56
      - ./.env
57
    environment:
58
      NODE_ENV: production
59
      # 容器内使用 Dockerfile 默认端口 3000，对外通过 APP_PORT 暴露（默认 23000）
60
      DSN: postgresql://${DB_USER:-postgres}:${DB_PASSWORD:-postgres}@postgres:5432/${DB_NAME:-claude_code_hub}
61
      REDIS_URL: redis://redis:6379
62
      AUTO_MIGRATE: ${AUTO_MIGRATE:-true}
63
      ENABLE_RATE_LIMIT: ${ENABLE_RATE_LIMIT:-true}
64
      SESSION_TTL: ${SESSION_TTL:-300}
65
      DB_POOL_IDLE_TIMEOUT: ${DB_POOL_IDLE_TIMEOUT:-20}
66
      DB_POOL_CONNECT_TIMEOUT: ${DB_POOL_CONNECT_TIMEOUT:-10}
67
      MAX_RETRY_ATTEMPTS_DEFAULT: ${MAX_RETRY_ATTEMPTS_DEFAULT:-2}
68
      LANGFUSE_SAMPLE_RATE: ${LANGFUSE_SAMPLE_RATE:-1.0}
69
      # 设置时区为上海
70
      TZ: Asia/Shanghai
71
    ports:
72
      - "${APP_PORT:-23000}:3000"
73
    volumes:
74
      # Node 诊断报告（report.*.json）持久化到宿主机，便于事后排查 SIGSEGV 等
75
      # native 崩溃。配合 Dockerfile 中 --report-* 启动参数生效（issue #1147）
76
      - ./data/reports:/app/reports
77
    restart: unless-stopped
78
    healthcheck:
79
      test:
80
        [
81
          "CMD",
82
          "node",
83
          "-e",
84
          "fetch('http://' + (process.env.HOSTNAME || '127.0.0.1') + ':3000/api/actions/health').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))",
85
        ]
86
      interval: 30s
87
      timeout: 5s
88
      retries: 3
89
      start_period: 30s

可以看到这里用了大量的${}环境变量，这要求我们要搭配.env文件来使用，来看官方的样例(重点更改)：

ADMIN_TOKEN:用于登录面板后台的密码
DB_PASSWORD数据库密码

1
# 管理员令牌（请务必更改此值以确保安全性）
2
ADMIN_TOKEN=change-me
3

4
# API 域名（分域部署时配置，Web UI 与 API 使用不同域名时需要设置）
5
# 用于 usage-doc 页面生成正确的客户端配置示例
6
# 单域名部署无需设置，留空则自动使用当前站点域名
7
# NEXT_PUBLIC_API_BASE_URL=https://api.example.com
8

9
# 自动迁移控制（生产环境默认开启）
10
# 设置为 false 可禁用自动迁移
11
AUTO_MIGRATE=true
12

13
# 数据库连接字符串（仅用于本地开发或非 Docker Compose 部署）
14
DSN="postgres://user:password@host:port/db_name"
15

16
# API Key Vacuum Filter（真空过滤器）
17
# - true (默认)：启用。用于在访问 DB 前“负向短路”无效 key，降低 DB 压力、抵御爆破
18
# - false：禁用（例如：需要排查问题或节省内存时）
19
ENABLE_API_KEY_VACUUM_FILTER="true"
20

21
# PostgreSQL 连接池配置（postgres.js）
22
# 说明：
23
# - 这些值是“每个应用进程”的连接池上限；k8s 多副本时需要按副本数分摊
24
# - 默认值：生产环境 20，开发环境 10（可按需覆盖）
25
DB_POOL_MAX=20
26
DB_POOL_IDLE_TIMEOUT=20                  # 空闲连接回收（秒）
27
DB_POOL_CONNECT_TIMEOUT=10               # 建立连接超时（秒）
28

29
# message_request 写入模式
30
# - async：异步批量写入（默认，降低 DB 写放大与连接占用）
31
# - sync：同步写入（兼容旧行为，但高并发下会增加请求尾部阻塞）
32
MESSAGE_REQUEST_WRITE_MODE=async
33

34
# message_request 异步批量参数（可选）
35
MESSAGE_REQUEST_ASYNC_FLUSH_INTERVAL_MS=250
36
MESSAGE_REQUEST_ASYNC_BATCH_SIZE=200
37
MESSAGE_REQUEST_ASYNC_MAX_PENDING=5000
38

39
# 数据库配置（Docker Compose 部署时使用）
40
DB_USER=postgres
41
DB_PASSWORD=your-secure-password_change-me
42
DB_NAME=claude_code_hub
43

44
# 应用配置
45
APP_PORT=23000
46
APP_URL=                                   # 应用访问地址（留空自动检测，生产环境建议显式配置）
47
                                           # 示例：https://your-domain.com 或 http://192.168.1.100:23000
48

49
# API 测试配置
50
# API 测试请求超时时间（毫秒），范围 5000-120000。未设置时默认 15000。
51
API_TEST_TIMEOUT_MS=15000
52

53
# Cookie 安全策略
54
# 功能说明：控制是否强制 HTTPS Cookie（设置 cookie 的 secure 属性）
55
# - true (默认)：仅允许 HTTPS 传输 Cookie，浏览器会自动放行 localhost 的 HTTP
56
# - false：允许 HTTP 传输 Cookie（会降低安全性，仅推荐用于内网部署）
57
# 警告：若设置为 true 且使用远程 HTTP 访问，浏览器将拒绝设置 Cookie 导致无法登录
58
ENABLE_SECURE_COOKIES=true
59

60
# Management REST API / legacy actions API
61
# - ENABLE_LEGACY_ACTIONS_API=false returns 410 Gone for legacy /api/actions execution.
62
# - LEGACY_ACTIONS_DOCS_MODE=hidden returns 410 for legacy docs even when execution stays enabled.
63
# - ENABLE_API_KEY_ADMIN_ACCESS=true allows admin-role DB API keys to call admin /api/v1 routes.
64
# - CSRF_SECRET signs cookie-authenticated management mutations; set the same value on all replicas.
65
ENABLE_LEGACY_ACTIONS_API=true
66
LEGACY_ACTIONS_DOCS_MODE=deprecated
67
LEGACY_ACTIONS_SUNSET_DATE=2026-12-31
68
ENABLE_API_KEY_ADMIN_ACCESS=false
69
CSRF_SECRET=
70

71
# Redis 配置（用于限流和 Session 追踪）
72
# 功能说明：
73
# - 限流功能：金额限制（5小时/周/月）+ Session 并发限制
74
# - Session 追踪：5 分钟上下文缓存优化（避免频繁切换供应商）
75
# - Fail Open 策略：Redis 不可用时自动降级，不影响服务可用性
76
ENABLE_RATE_LIMIT=true                  # 是否启用限流功能（默认：true）
77
REDIS_URL=redis://localhost:6379        # Redis 连接地址（Docker 部署使用 redis://redis:6379，支持 rediss:// TLS）
78
REDIS_TLS_REJECT_UNAUTHORIZED=true      # 是否验证 Redis TLS 证书（默认：true）
79
                                        # 设置为 false 可跳过证书验证，用于自签证书或共享证书场景
80
                                        # 仅在 rediss:// 协议时生效
81

82
# API Key 鉴权缓存（Vacuum Filter -> Redis -> DB）
83
# 说明：需要 ENABLE_RATE_LIMIT=true 且配置 REDIS_URL 才会启用 Redis 缓存；否则自动回落到 DB。
84
API_KEY_AUTH_CACHE_TTL_SECONDS="60"      # 鉴权缓存 TTL（秒，默认 60，最大 3600）
85
ENABLE_API_KEY_REDIS_CACHE="true"        # 是否启用 API Key Redis 缓存（默认：true）
86

87
# Session 配置
88
# 降低该值会按签发时间收紧已签发 ADMIN_TOKEN 签名 cookie 的剩余寿命，且不会延长其原始 exp。
89
AUTH_SESSION_TTL_SECONDS=604800         # Web UI 登录态过期时间（秒，默认 604800 = 7 天，范围 60-31536000）
90
SESSION_TTL=300                         # 代理请求上下文缓存时间（秒，默认 300 = 5 分钟；不控制 Web UI 登录态）
91
STORE_SESSION_MESSAGES=false            # 会话消息存储模式（默认：false）
92
                                        # - false：存储请求/响应体但对 message 内容脱敏 [REDACTED]
93
                                        # - true：原样存储 message 内容（注意隐私和存储空间影响）
94
                                        # 警告：启用后会增加 Redis/DB 存储空间，且包含敏感信息
95
STORE_SESSION_RESPONSE_BODY=true        # 是否在 Redis 中存储会话响应体（默认：true）
96
                                        # - true：存储（SSE/JSON），用于调试/定位问题（Redis 临时缓存）
97
                                        # - false：不存储响应体（注意：不影响本次请求处理；仅影响后续查看 response body）
98
                                        # 说明：该开关不影响内部统计读取响应体（tokens/费用统计、SSE 假 200 检测仍会进行）
99

100
# Dashboard 配置
101
DASHBOARD_LOGS_POLL_INTERVAL_MS=5000    # 日志页自动刷新轮询间隔（毫秒，默认 5000，范围 250-60000）
102

103
# 熔断器配置
104
# 功能说明：控制网络错误是否计入熔断器失败计数
105
# - false (默认)：网络错误（DNS 解析失败、连接超时、代理连接失败等）不计入熔断器，仅供应商错误（4xx/5xx HTTP 响应）计入
106
# - true：所有错误（包括网络错误）都计入熔断器失败计数
107
# 使用场景：
108
# - 默认关闭：适用于网络不稳定环境（如使用代理），避免因临时网络抖动触发熔断器
109
# - 启用：适用于网络稳定环境，连续网络错误也应触发熔断保护，避免持续请求不可达的供应商
110
ENABLE_CIRCUIT_BREAKER_ON_NETWORK_ERRORS=false
111

112
# 端点级别熔断器
113
# 功能说明：控制是否启用端点级别的熔断器
114
# - false (默认)：禁用端点熔断器，所有启用的端点均可使用
115
# - true：启用端点熔断器，连续失败的端点会被临时屏蔽（默认 3 次失败后熔断 5 分钟）
116
ENABLE_ENDPOINT_CIRCUIT_BREAKER=false
117

118
# 供应商缓存配置
119
# 功能说明：控制是否启用供应商进程级缓存
120
# - true (默认)：启用缓存，30s TTL + Redis Pub/Sub 跨实例即时失效，提升供应商查询性能
121
# - false：禁用缓存，每次请求直接查询数据库（适用于调试或单机低并发场景）
122
ENABLE_PROVIDER_CACHE=true
123

124
# Fetch 连接超时配置
125
# 功能说明：控制 TCP 连接建立超时时间（包括 DNS 查询、TCP 握手、TLS 握手）
126
# - 默认值：30000 毫秒（30 秒）
127
# - 取值范围：建议 5000-120000 毫秒（5-120 秒）
128
# 使用场景：
129
# - 缩短此值可快速切换到备用供应商，当供应商被攻击或无响应时
130
# - 增加此值适用于网络不稳定环境，避免因网络抖动导致连接失败
131
FETCH_CONNECT_TIMEOUT=30000
132

133
# Fetch 响应头超时配置
134
# 功能说明：控制等待响应头的超时时间（通常可近似理解为“等待首字节/首包”的上限）
135
# - 默认值：600000 毫秒（600 秒）
136
# - 取值范围：建议 10000-600000 毫秒（10-600 秒）
137
# 使用场景：
138
# - 需要支持长时间首字节等待（例如某些模型/代理的排队或冷启动）时，可适当增大
139
# - 希望更快失败并切换供应商时，可适当减小
140
FETCH_HEADERS_TIMEOUT=600000
141

142
# Fetch 响应体超时配置
143
# 功能说明：控制请求/响应体传输超时（undici 会监控 body 数据接收间隔，超时则中断请求）
144
# - 默认值：600000 毫秒（600 秒）
145
# - 取值范围：建议 10000-600000 毫秒（10-600 秒）
146
# 使用场景：
147
# - 流式响应或长推理模型：建议保留较大值，避免被 undici 默认 300s 先行终止
148
# - 希望快速失败并切换供应商：可适当减小
149
FETCH_BODY_TIMEOUT=600000
150
MAX_RETRY_ATTEMPTS_DEFAULT=2                # 单供应商最大尝试次数（含首次调用），范围 1-10，留空使用默认值 2
151

152
# Langfuse Observability (optional, auto-enabled when keys are set)
153
# 功能说明：企业级 LLM 可观测性集成，自动追踪所有代理请求的完整生命周期
154
# - 配置 PUBLIC_KEY 和 SECRET_KEY 后自动启用
155
# - 支持 Langfuse Cloud 和自托管实例
156
LANGFUSE_PUBLIC_KEY=                        # Langfuse project public key (pk-lf-...)
157
LANGFUSE_SECRET_KEY=                        # Langfuse project secret key (sk-lf-...)
158
LANGFUSE_BASE_URL=https://cloud.langfuse.com  # Langfuse server URL (self-hosted or cloud)
159
LANGFUSE_SAMPLE_RATE=1.0                    # Trace sampling rate (0.0-1.0, default: 1.0 = 100%)
160
LANGFUSE_DEBUG=false                        # Enable Langfuse debug logging
161

162
# 智能探测配置
163
# 功能说明：当熔断器处于 OPEN 状态时，定期探测供应商以实现更快恢复
164
# - ENABLE_SMART_PROBING：是否启用智能探测（默认：false）
165
# - PROBE_INTERVAL_MS：探测周期间隔（毫秒，默认：30000 = 30秒）
166
# - PROBE_TIMEOUT_MS：单次探测超时时间（毫秒，默认：5000 = 5秒）
167
# 工作原理：
168
# - 定期检查处于 OPEN 状态的熔断器
169
# - 使用轻量级测试请求探测供应商
170
# - 探测成功则提前将熔断器转为 HALF_OPEN 状态
171
ENABLE_SMART_PROBING=false
172
PROBE_INTERVAL_MS=30000
173
PROBE_TIMEOUT_MS=5000
174

175
# Provider Endpoint Probing (always enabled)
176
# Probes all enabled endpoints based on dynamic intervals and refreshes endpoint selection ranking.
177
# Note: No ENABLE switch, enabled by default; tune via parameters below.
178
#
179
# Dynamic Interval Rules (in priority order):
180
# 1. Timeout Override (10s): If endpoint's lastProbeErrorType === "timeout" and not recovered (lastProbeOk !== true)
181
# 2. Single-Vendor (10min): If vendor has only 1 enabled endpoint
182
# 3. Base Interval (default): All other endpoints
183
#
184
# ENDPOINT_PROBE_INTERVAL_MS controls the base interval. Single-vendor and timeout intervals are fixed.
185
ENDPOINT_PROBE_INTERVAL_MS=60000
186
# When no endpoints are due, scheduler will still poll DB periodically to pick up config changes.
187
# Default: min(ENDPOINT_PROBE_INTERVAL_MS, 30000)
188
ENDPOINT_PROBE_IDLE_DB_POLL_INTERVAL_MS=30000
189
ENDPOINT_PROBE_TIMEOUT_MS=5000
190
ENDPOINT_PROBE_CONCURRENCY=10
191
ENDPOINT_PROBE_CYCLE_JITTER_MS=1000
192
ENDPOINT_PROBE_LOCK_TTL_MS=30000
193
# Probe method: TCP (default, no HTTP request / no access log), HEAD, GET
194
ENDPOINT_PROBE_METHOD=TCP
195

196
# 探测日志保留与清理
197
# - 所有探测结果（成功/失败）均记录到历史表
198
# - 自动清理任务每 24 小时运行，删除过期记录
199
ENDPOINT_PROBE_LOG_RETENTION_DAYS=1
200
ENDPOINT_PROBE_LOG_CLEANUP_BATCH_SIZE=10000

更改过后，只需要按如下操作在VPS里执行命令即可：

1
mkdir -p ~/cch
2
cd ~/cch
3
# 创建编辑compose文件
4
nano docker-compose.yml
5
# 创建编辑环境变量文件
6
nano .env
7
# 启动容器
8
sudo docker compose up -d

Nginx配置#

关于SSL证书的申请和Nginx配置文件编辑，在笔者过往文章中提到很多了，这里只贴一下server配置：

1
# ==================== Claude-Code-Hub - HTTP ====================
2
server {
3
    listen 80;
4
    server_name <your-domain>;
5

6
    # HTTP自动跳转HTTPS
7
    return 301 https://$host$request_uri;
8
}
9

10
# ==================== Claude-Code-Hub - HTTPS ====================
11
server {
12
    listen 443 ssl http2;
13
    server_name <your-domain>;
14

15
    ssl_certificate /etc/letsencrypt/live/<your-domain>/fullchain.pem;
16
    ssl_certificate_key /etc/letsencrypt/live/<your-domain>/privkey.pem;
17

18
    proxy_buffering off;
19
    proxy_request_buffering off;
20
    proxy_cache off;
21

22
    location / {
23
        proxy_pass http://127.0.0.1:23000;
24
        proxy_http_version 1.1;
25

26
        # WebSocket 支持
27
        proxy_set_header Upgrade $http_upgrade;
28
        proxy_set_header Connection "upgrade";
29

30
        # 传递真实客户端信息
31
        proxy_set_header Host $host;
32
        proxy_set_header X-Real-IP $remote_addr;
33
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
34
        proxy_set_header X-Forwarded-Proto $scheme;
35

36
        # 超时设置
37
        proxy_connect_timeout 60s;
38
        proxy_send_timeout 7200s;
39
        proxy_read_timeout 7200s;
40

41
        chunked_transfer_encoding on;
42
        gzip off;
43
      }
44
}

相关链接#

Docker部署#

Nginx配置#