Rhex社区1Panel面板详细部署教程（纯新手向）

Rhex 社区程序的最新版本都是在 GitHub 发布的，Gitee 很久没更新了。你需要有一个稳定的网络环境能访问到 GitHub，这不是必备条件，但也是不受别人支配的先决条件。

1、前期准备工作

1.1、一台服务器，Linux 操作系统

原则上 Windows 也可以，只要能安装 Docker 就能运行，但本文不赘述 Windows 下的部署。配置最好在 4C4G 以上，Node.js 运行很吃内存。本教程演示全程在一台闲置的 4C4G 服务器上进行。

1.2、安装好 1Panel 面板

能访问到，并做好基础设置，这里不赘述。

2、选择部署方式

2.1、Docker 镜像部署方式

我本来提供了3种部署方案，最后发现其实也没什么用。本教程只提供一种部署方式。

方案 A：一键 Docker 部署方案 – 会生成 5 个容器：Setup 容器（Rhex 安装容器，安装完成后停止）、Web 容器（Rhex 的 Web 端）、Worker 容器（后台任务、Redis 队列等）、PostgreSQL（数据库）、Redis（Redis 缓存）。

3、详细部署教程

3.1、1Panel 的 Docker 相关设置

3.1.1、安装 OpenResty

在应用商店选择安装即可，方便后面进行反向代理。

3.1.2、容器相关设置

容器 → 配置 → 镜像加速 → 设置，加入如下地址：

腾讯云服务器有天然优势，可使用内网 Docker Hub 加速：

ts
https://mirror.ccs.tencentyun.com

阿里云及其他国内服务器可使用：

ts
`https://docker.1panel.live
`https://docker.1panel.dev 
`https://docker.1ms.run

3.2、方案A：全量Docker部署方式

3.2.1、在1Panel面板的左侧系统---->文件，找合适的目录（完全取决于你自己）创建文件夹，命名为rhex（不是这名字也行，随你的意，只要你能记住）如下图：

3.2.2、创建 docker-compose 文件

去 GitHub 作者的项目里下载 docker-compose.yml，项目地址：https://github.com/lovedevpanda/Rhex
考虑到国内环境拉取 GitHub 镜像可能遇到网络问题，需要修改 docker-compose.yml文件里的 image 地址：
将：

text
image: ghcr.io/lovedevpanda/rhex:latest

替换成：

text
image: ghcr.nju.edu.cn/lovedevpanda/rhex:latest

注：ghcr.nju.edu.cn加速网站来源于南京大学开源镜像站，并非个人提供，请放心使用。

对于不方便下载的用户，直接贴出修改好的 docker-compose.yml：

yaml
x-app-environment: &app-environment
  DATABASE_URL: postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgres}@postgres:5432/${POSTGRES_DB:-bbs}?schema=public
  REDIS_URL: redis://redis:6379
  REDIS_PASSWORD: ${REDIS_PASSWORD:-}
  REDIS_DB: ${REDIS_DB:-}

x-app-service: &app-service
  image: ghcr.nju.edu.cn/lovedevpanda/rhex:latest
  pull_policy: always
  init: true
  env_file:
    - .env
  volumes:
    - ./uploads:/app/uploads
    - ./addons:/app/addons

services:
  postgres:
    image: postgres:18
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB:-bbs}
      POSTGRES_USER: ${POSTGRES_USER:-postgres}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
      TZ: ${TZ:-Asia/Shanghai}
    ports:
      - "127.0.0.1:${POSTGRES_PORT:-5432}:5432"
    volumes:
      - postgres_data:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U ${POSTGRES_USER:-postgres} -d ${POSTGRES_DB:-bbs}"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 10s

  redis:
    image: redis:latest
    restart: unless-stopped
    command:
      - sh
      - -c
      - |
        set -eu
        if [ -n "$${REDIS_PASSWORD:-}" ]; then
          exec redis-server --appendonly yes --requirepass "$${REDIS_PASSWORD}"
        fi
        exec redis-server --appendonly yes
    environment:
      REDIS_PASSWORD: ${REDIS_PASSWORD:-}
    ports:
      - "127.0.0.1:${REDIS_PORT:-6379}:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD-SHELL", "if [ -n \"$${REDIS_PASSWORD:-}\" ]; then redis-cli -a \"$${REDIS_PASSWORD}\" --no-auth-warning ping; else redis-cli ping; fi"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 5s

  setup:
    <<: *app-service
    restart: on-failure
    environment: *app-environment
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    command: ["pnpm", "run", "setup:prod"]

  postgres-backup:
    image: postgres:18
    profiles:
      - backup
    restart: "no"
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      POSTGRES_DB: ${POSTGRES_DB:-bbs}
      POSTGRES_USER: ${POSTGRES_USER:-postgres}
      PGPASSWORD: ${POSTGRES_PASSWORD:-postgres}
      TZ: ${TZ:-Asia/Shanghai}
    volumes:
      - ./backups:/backups
    command:
      - sh
      - -c
      - |
        set -eu
        mkdir -p /backups
        pg_dump -h postgres -U "$${POSTGRES_USER:-postgres}" -d "$${POSTGRES_DB:-bbs}" -Fc -f "/backups/rhex-$$(date +%Y%m%d-%H%M%S).dump"

  web:
    <<: *app-service
    restart: unless-stopped
    stop_grace_period: 30s
    environment:
      <<: *app-environment
      HOSTNAME: ${HOSTNAME:-0.0.0.0}
      PORT: ${PORT:-3000}
    depends_on:
      postgres:
        condition: service_healthy
        restart: true
      redis:
        condition: service_healthy
        restart: true
      setup:
        condition: service_completed_successfully
    ports:
      - "${PORT:-3000}:${PORT:-3000}"
    command: ["pnpm", "run", "start"]

  worker:
    <<: *app-service
    restart: unless-stopped
    stop_grace_period: 30s
    environment:
      <<: *app-environment
      INTERNAL_REVALIDATION_ORIGIN: ${INTERNAL_REVALIDATION_ORIGIN:-http://web:${PORT:-3000}}
    depends_on:
      postgres:
        condition: service_healthy
        restart: true
      redis:
        condition: service_healthy
        restart: true
      setup:
        condition: service_completed_successfully
    command: ["pnpm", "run", "worker"]

volumes:
  postgres_data:
  redis_data:

把 docker-compose.yml文件直接上传到刚才创建的 rhex文件夹。你可以直接上传，或在 1Panel 面板里新建文件，后缀必须是 .yml，然后把上面的代码贴进去并保存，此为方法一。

另一种方法：点击左侧“容器 → 编排 → 创建编排 → 填写文件夹”，但此时文件保存路径在 /data/1panel/docker/compose/下。这种方法极不推荐，因为 Rhex 项目会在 docker-compose.yml所在目录生成插件目录 addons或附件目录 uploads，所以极不推荐，但也可以用，这里提一嘴。

现在按方法一继续。在 rhex目录下已经有了 docker-compose.yml文件。在这个阶段，可以通过更改docker-compose.yml文件更改 Rhex 的端口。

3.2.3、创建配置文件 `.env`

去 GitHub 作者的项目里下载 .env.example文件，项目地址：https://github.com/lovedevpanda/Rhex，下载后改名为 .env，然后上传到 rhex目录下。或者直接在 1Panel面板文件管理里的创建的rhex文件根目录，和 docker-compose.yml同级的文件夹下，新建 .env文件（注意这个文件前面有 .的）。

以下是核心配置文件的内容（已做必要说明）：

env
# =============================================================================
# 【必填】核心运行参数
# -----------------------------------------------------------------------------
#
# 1. 宿主机直接运行
#
# 2. Docker Compose 运行
#
# 按部署方式二选一修改即可，不需要同时手改两套数据库地址。
# =============================================================================
# PostgreSQL 连接串，Prisma / 业务库均从这里读取
#
# 宿主机时，请写你本机可访问的地址。
# Docker Compose 时，这个值会被 Compose 自动覆盖，不需要手动改成 `postgres`。
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/bbs?schema=public"

# Session Cookie 的签名密钥，至少 32 位随机串；同时作为
# AUTH_FLOW_SECRET 的回落值（OAuth / Passkey 流程签名）
SESSION_SECRET="replace-with-a-long-random-secret"

# 验证码 HMAC 主密钥，内置图形验证码 + PoW 验证码都会读取；
# 同时作为 POW_CAPTCHA_SECRET_KEY 的回落值
CAPTCHA_SECRET_KEY="replace-with-a-long-random-secret"

# Redis 连接串，异步任务 / 分布式锁 / 队列 / 缓存均依赖。
# 如果 Redis 密码或分库已写在连接串里，会优先使用连接串里的值，例如：
# REDIS_URL="redis://:password@127.0.0.1:6379/2"
#
# 宿主机直跑时通常保持 `127.0.0.1` / `localhost`；
# Docker Compose 时，这个值会被 Compose 自动覆盖，不需要手动改成 `redis`。
REDIS_URL="redis://127.0.0.1:6379"

# =============================================================================
# 【可选】站点地址（用于生成外链、OAuth 回调、邮件中的绝对 URL）
# 运行时读取；优先级：SITE_URL > APP_URL > NEXT_PUBLIC_SITE_URL
# 未设置时回落到请求头 `x-forwarded-proto` / `host`
# =============================================================================
# SITE_URL="https://example.com"
# APP_URL="https://example.com"
# NEXT_PUBLIC_SITE_URL="https://example.com"

# 后台 worker 请求 Web 进程执行 Next.js 缓存失效时使用。
# Docker Compose 默认会用 http://web:${PORT:-3000}。
# 宿主机直跑 worker 时可设置为 http://127.0.0.1:3000，或使用公网 SITE_URL / APP_URL 回退。
# INTERNAL_REVALIDATION_ORIGIN="http://127.0.0.1:3000"
# 未设置密钥时回落到 SESSION_SECRET；如果 Web 和 worker 属于不同信任边界，建议单独设置。
# INTERNAL_REVALIDATION_SECRET="replace-with-a-long-random-secret"

# =============================================================================
# 【可选】编译静态资源 CDN
# -----------------------------------------------------------------------------
# 用于托管 `next build` 生成的 JS / CSS 等 `/_next/static/` 资源。
# 填 CDN 域名或前缀即可，不要在末尾追加 `/_next/static`。
# 设置后需要把构建产物 `.next/static/` 映射或上传为 CDN 的 `/_next/static/`。
# 预构建 Docker 镜像会在容器启动时读取该变量；不需要重新构建镜像。
# =============================================================================
# NEXT_ASSET_PREFIX="https://cdn.example.com"

# =============================================================================
# 【可选】初始化管理员账号
# 仅首次执行 `npm run setup` / `npm run prisma:seed` 时生效；
# 管理员已存在时这些变量会被忽略
# =============================================================================
SEED_ADMIN_USERNAME="admin"
SEED_ADMIN_PASSWORD="ChangeMe_123456"
SEED_ADMIN_EMAIL="admin@rhex.im"
SEED_ADMIN_NICKNAME="秦始皇"

# =============================================================================
# 【可选】Docker Compose 内置 PostgreSQL / Redis
# 仅用于 `docker compose`
# =============================================================================
POSTGRES_DB="bbs"
POSTGRES_USER="postgres"
POSTGRES_PASSWORD="postgres"
POSTGRES_PORT="5432"
REDIS_PORT="6379"
TZ="Asia/Shanghai"

# =============================================================================
# 【可选】Redis 命名与观测
# =============================================================================

# 所有 Redis Key 的统一前缀（默认 "rhex"）
REDIS_KEY_PREFIX="rhex"

# Redis ACL 用户名；未设置时使用 Redis 默认用户
# REDIS_USERNAME="default"

# Redis 密码；当 REDIS_URL 未包含密码时生效
# Docker Compose 内置 Redis 也会读取该值并启用 requirepass
# REDIS_PASSWORD=""

# Redis 分库编号；当 REDIS_URL 未包含 `/db` 路径时生效，默认使用 0
# REDIS_DB="0"

# Redis 客户端 CLIENT SETNAME 前缀，便于在 `CLIENT LIST` 中区分进程（默认 "rhex"）
# REDIS_CLIENT_NAME_PREFIX="rhex"

# SLOWLOG 采样周期，单位毫秒；默认 60000，范围 5000-600000
# REDIS_SLOWLOG_SAMPLE_INTERVAL_MS="60000"


# =============================================================================
# 【可选】鉴权与验证码
# =============================================================================

# 外部登录流程（OAuth / Passkey）状态签名密钥；
# 未设置时自动回落到 SESSION_SECRET
# AUTH_FLOW_SECRET=""

# PoW 验证码专用密钥；未设置时自动回落到 CAPTCHA_SECRET_KEY
# POW_CAPTCHA_SECRET_KEY=""

# PoW 验证码难度（0 前导位数），默认 4（移动端回落 3），范围 1-6
# POW_CAPTCHA_DIFFICULTY="4"

# PoW 验证码有效期（秒），默认 40，范围 15-300
# POW_CAPTCHA_EXPIRE_SECONDS="40"

# =============================================================================
# 【可选】后台任务 Runtime
# -----------------------------------------------------------------------------
# BACKGROUND_JOB_WEB_RUNTIME 取值：
#   - "worker-only"（生产推荐）：Web/API 仅入队，后台消费由 `npm run worker` 独立进程承担
#   - "hybrid"：Web/API 同时消费后台任务（兼容旧行为，单机部署可用）
#   - "auto"（默认）：开发环境按需拉起内存消费者；生产环境等同 "worker-only"
# =============================================================================
BACKGROUND_JOB_WEB_RUNTIME="worker-only"

# 单进程并发消费数，默认 10，硬上限 32
BACKGROUND_JOB_CONCURRENCY="10"

# 单任务最大重试次数（进入死信前），默认 3，范围 1-20
BACKGROUND_JOB_MAX_ATTEMPTS="3"

# 指数退避基础时长（毫秒），默认 5000
BACKGROUND_JOB_RETRY_BASE_MS="5000"

# 指数退避上限（毫秒），默认 300000（5 分钟）
BACKGROUND_JOB_RETRY_MAX_MS="300000"

# 以下参数用于对后台任务进行精细调优，大多数场景无需修改
# ---------------------------------------------------------

# Redis Stream 最大长度（MAXLEN ~），默认 10000
# BACKGROUND_JOB_STREAM_MAX_LENGTH="10000"

# XREADGROUP 阻塞超时（毫秒），默认 5000
# BACKGROUND_JOB_BLOCK_TIMEOUT_MS="5000"

# XREADGROUP 单次读取批大小，默认 10，范围 1-200
# BACKGROUND_JOB_READ_BATCH_SIZE="10"

# Pending 任务被判定为空闲的阈值（毫秒），默认 900000（15 分钟）
# BACKGROUND_JOB_PENDING_IDLE_MS="900000"

# 一次 XAUTOCLAIM 的批大小，默认 20，范围 1-200
# BACKGROUND_JOB_PENDING_CLAIM_BATCH_SIZE="20"

# Pending 扫描节拍（毫秒），默认 15000
# BACKGROUND_JOB_PENDING_SWEEP_INTERVAL_MS="15000"

# Stream 修剪节拍（毫秒），默认 60000
# BACKGROUND_JOB_PRUNE_SWEEP_INTERVAL_MS="60000"

# 延迟任务批量转正规模，默认 50，范围 1-500
# BACKGROUND_JOB_DELAYED_PROMOTION_BATCH_SIZE="50"

# Redis 死信队列最大长度，默认 1000
# BACKGROUND_JOB_DEAD_LETTER_MAX_LENGTH="1000"

# 内存版（非 Redis）死信队列最大长度，默认 200
# BACKGROUND_JOB_IN_MEMORY_DEAD_LETTER_MAX_LENGTH="200"

# 管理后台一次全表扫描最大条数，默认 10000
# BACKGROUND_JOB_FULL_SCAN_MAX_ENTRIES="10000"

# 幂等键 TTL（秒），默认 86400（1 天），范围 60-604800
# BACKGROUND_JOB_IDEMPOTENCY_TTL_SECONDS="86400"

# Lane 崩溃重启基础退避（毫秒），默认 1000
# BACKGROUND_JOB_LANE_RESTART_BASE_DELAY_MS="1000"

# Lane 崩溃重启上限退避（毫秒），默认 30000
# BACKGROUND_JOB_LANE_RESTART_MAX_DELAY_MS="30000"


# =============================================================================
# 【可选】帖子竞拍结算
# =============================================================================

# 单批结算拍卖数量，默认 100，上限 500
# POST_AUCTION_SETTLEMENT_BATCH_SIZE="100"

# 恢复扫描批大小，默认 100，上限 500
# POST_AUCTION_SETTLEMENT_RECOVERY_BATCH_SIZE="100"

# 结算恢复轮询周期（毫秒），默认 60000
# POST_AUCTION_SETTLEMENT_RECOVERY_INTERVAL_MS="60000"

# =============================================================================
# 【可选】AI 助手
# =============================================================================

# 单个 AI 回复任务"处理中"超时阈值（毫秒），默认 300000（5 分钟），
# 超过阈值仍未完成的任务会被判定为失联并允许重新调度
# AI_REPLY_PROCESSING_STALE_MS="300000"

# =============================================================================
# 【可选】RSS 抓取中心
# =============================================================================

# 执行日志保留时长（秒），默认 259200（3 天），最小 300
# RSS_LOG_RETENTION_SECONDS="259200"

# 队列快照保留时长（秒），默认 604800（7 天），最小 300
# RSS_QUEUE_RETENTION_SECONDS="604800"


# =============================================================================
# 【可选】通用日志存储（后台任务日志 / RSS 执行日志共用）
# =============================================================================

# 单个日志 ZSET 的最大条目数（近似修剪），默认 10000，范围 100-1000000
# LOG_STORE_MAX_ENTRIES="10000"

# =============================================================================
# 【可选】系统通知 Webhook（用户在个人中心订阅的站外推送）
# =============================================================================

# 单次请求超时（毫秒），默认 5000
# SYSTEM_NOTIFICATION_WEBHOOK_TIMEOUT_MS="5000"

# 最大重试次数，默认 4
# SYSTEM_NOTIFICATION_WEBHOOK_MAX_ATTEMPTS="4"

# 指数退避基础时长（毫秒），默认 15000
# SYSTEM_NOTIFICATION_WEBHOOK_RETRY_BASE_MS="15000"

# 指数退避上限（毫秒），默认 300000（5 分钟）
# SYSTEM_NOTIFICATION_WEBHOOK_RETRY_MAX_MS="300000"

有几个参数是必填的：

SESSION_SECRET：随便找个网站，生成 32 位随机数（最好字母+数字即可）。
CAPTCHA_SECRET_KEY：同样生成 32 位随机数。
SITE_URL / APP_URL / NEXT_PUBLIC_SITE_URL：去除前面的 #号，如实填写你的站点地址。
INTERNAL_REVALIDATION_ORIGIN：去除前面的 #号，并按照以下示例修改（注意去掉原文件里的双引号）： INTERNAL_REVALIDATION_ORIGIN=http://rhex-web-1:3000这个端口要与 docker-compose.yml里的一致（如果你前面改过端口）。
INTERNAL_REVALIDATION_SECRET：可根据需要自行修改，如果修改也要去除前面的 #号。
修改的地方如下图所示：

还有一个修改点是初始化管理员账号：

env
SEED_ADMIN_USERNAME="admin"
SEED_ADMIN_PASSWORD="ChangeMe_123456"
SEED_ADMIN_EMAIL="admin@rhex.im"
SEED_ADMIN_NICKNAME="秦始皇"

根据自己的需要修改即可。其他如 CDN 等选项，根据需要填写并启用（启用就是去除前面的 #号注释）。

至此，基本配置完成。

3.2.4、编排并启动容器

点击左侧“容器 → 进入编排 → 创建 → 点击路径选择”。

点击前面那个文件小图标，选择 docker-compose.yml所在的文件夹，并选中 docker-compose.yml。

点击确认后，如下图：

确认路径，同时可以看到已经加载了 .env的环境变量。然后点击保存。
如下图，开始拉取镜像进行构建：

等待即可，不需要进行其他操作。

可能遇到的错误及解决方法：

错误 1：Failed to Setup IP tables: ... 这是 1Panel 至今没有解决的 bug，运行一段时间后应用商店升级应用都会出现防火墙问题。解决方法：容器 → 设置 → 重启 Docker。
错误 2：Bind for 127.0.0.1:6379 failed: port is already allocated 端口被占用。如果服务器已经安装了一些镜像，需要注意端口占用。如果 Redis 端口被占，可以去修改 docker-compose.yml的端口，同时也要修改 .env里的对应的端口。

看到进度基本不动时，返回列表页，可以看到以下 5 个容器就是 Rhex 的容器：

可以查看日志，确认安装是否完成。