Claper Docker Compose 部署指南

目标：在一台 Linux 服务器上从零用 Docker Compose 部署 Claper 3.2.0（Elixir/Phoenix LiveView + PostgreSQL 双服务栈），完成管理员登录、改密、创建演示事件与观众页验证；全部命令与回显均在 Ubuntu 22.04 服务器环境实测（2026-11-01），排障实录见「常见问题」。选型背景见《Claper 介绍与选型指南》。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Docker Engine 29.x + Docker Compose v2（docker compose 子命令形态）
Claper 版本：3.2.0（GitHub Release v3.2.0，2026-10-27 发布；容器镜像标签为 3.2.0，无 v 前缀，见 11.1）
应用镜像：ghcr.io/claperco/claper:3.2.0（内置 Elixir 1.18.4 / OTP 28 / Phoenix 1.7.24 / LiveView 1.0.19 / Cowboy 2.19.0）
数据库镜像：postgres:15（官方 compose 指定）
对外端口：宿主机 8129 → 应用内部 4000（Phoenix/Cowboy 监听）；PostgreSQL 不对宿主机暴露
自定义网络：claper-net，显式子网 10.89.56.0/24
数据持久化：命名卷 claper-db（PG 数据目录）、claper-uploads（幻灯片转换产物）
Compose 项目名：claper-3.2.0-stack（注意：Compose 会把项目名中的 . 规范化掉，实际资源前缀为 claper-320-stack_，见 11.5）
项目目录（本文档视角）：/opt/claper
示例管理账号：admin@claper.co，初始口令 claper（官方种子账号），部署后立即改为 q1w2e3r4

二、镜像选型说明

Claper 官方只发布 GitHub Container Registry 镜像 ghcr.io/claperco/claper（仓库 README 徽章与官方 compose 均指向 ghcr，Docker Hub 无官方镜像）。标签规律实测如下：

数字标签：3.2.0、3.2、3、3.1.2…（不带 v 前缀，与 GitHub Release 的 v3.2.0 不同名）
滚动标签：latest、main（dev 分支构建为 dev）

registry 标签清单实测（匿名 token 查询，节选）：

TOKEN=$(curl -s "https://ghcr.io/token?scope=repository:claperco/claper:pull&service=ghcr.io" \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["token"])')
curl -s -H "Authorization: Bearer $TOKEN" "https://ghcr.io/v2/claperco/claper/tags/list" \
  | python3 -c 'import sys,json;ts=json.load(sys.stdin)["tags"];print([t for t in ts if t.startswith("3") or t in ("latest","main","dev")]);print("total",len(ts))'

['latest', 'main', 'dev', '3.0.0', '3.0', '3', '3.1.0', '3.1', '3.1.1', '3.1.2', '3.2.0', '3.2']
total 54

生产部署建议锁定数字标签（如 3.2.0）而非 latest，升级走显式改标签 + docker compose up -d（官方另有 Updating 文档）。数据库侧官方 compose 固定 postgres:15，实测可用；Claper 无外部 Redis/消息队列依赖，后台任务由 Oban 落在 PostgreSQL 内。

💡 技术拓展：Phoenix 应用的容器镜像有两种常见形态——release 镜像（mix release 产物，含 Erlang VM 与自研启动脚本 bin/<app>，无源码无 mix，体积小、启动即运行）与运行时自建镜像（Debian + 自装 Erlang 再跑 release）。Claper 官方镜像属前者：容器内 /app/bin/claper 即 release 管理脚本，运维命令详见《Claper 3.2.0 常用 CLI 命令与工具详解》（发布后补链）。

三、前置条件

已安装 Docker Engine 与 Compose v2，当前用户可执行 docker：

docker --version && docker compose version

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

宿主机端口 8129 空闲：

ss -ltn | grep ':8129 ' || echo "8129 FREE"

8129 FREE

已安装 openssl（用于生成 SECRET_KEY_BASE）：

openssl version

OpenSSL 3.0.13 30 Jan 2024 (Library: OpenSSL 3.0.13 30 Jan 2024)

服务器可访问 ghcr.io。实测备注：本机 Docker 守护进程已配置代理，docker pull 直连 ghcr 正常；但宿主机 curl 直连 raw.githubusercontent.com 当时超时，改用 jsDelivr CDN（https://cdn.jsdelivr.net/gh/<org>/<repo>@<tag>/<path>）成功获取官方仓库文件——若你需要下载 .env.sample 等仓库文件而官方 raw 地址不通，走该国内可达渠道。

四、部署步骤

4.1 创建项目目录与 compose 文件

mkdir -p /opt/claper && cd /opt/claper
cat > docker-compose.yml <<'EOF'
name: claper-3.2.0-stack

services:
  db:
    image: postgres:15
    container_name: claper-3.2.0-db
    volumes:
      - "claper-db:/var/lib/postgresql/data"
    healthcheck:
      test:
        - CMD
        - pg_isready
        - "-q"
        - "-d"
        - "claper"
        - "-U"
        - "claper"
      retries: 3
      timeout: 5s
    environment:
      POSTGRES_PASSWORD: claper
      POSTGRES_USER: claper
      POSTGRES_DB: claper
    networks:
      - claper-net
  app:
    image: ghcr.io/claperco/claper:3.2.0
    container_name: claper-3.2.0-app
    ports:
      - 8129:4000
    volumes:
      - "claper-uploads:/app/uploads"
    healthcheck:
      test: curl --fail http://localhost:4000 || exit 1
      retries: 3
      start_period: 20s
      timeout: 5s
    env_file: .env
    depends_on:
      db:
        condition: service_healthy
    networks:
      - claper-net

volumes:
  claper-db:
    driver: local
  claper-uploads:
    driver: local

networks:
  claper-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.56.0/24
EOF

逐项说明：

name: 显式声明项目名，避免目录改名导致资源前缀漂移；
db 侧 healthcheck 用 pg_isready 探活，app 通过 depends_on.condition: service_healthy 等库就绪再启动（Claper 启动时自动跑 Ecto 迁移，库未就绪会直接失败退出）；
app 侧 healthcheck 用 curl --fail http://localhost:4000 探 HTTP 根路径；
子网 10.89.56.0/24 按本机地址规划显式固定，防止多栈并行时 Docker 自动分配冲突。

4.2 生成 .env 环境变量文件

cd /opt/claper
SECRET=$(openssl rand -base64 48)
cat > .env <<EOF
BASE_URL=http://localhost:8129
DATABASE_URL=postgres://claper:claper@db:5432/claper
SECRET_KEY_BASE=$SECRET
PRESENTATION_STORAGE=local
PRESENTATION_STORAGE_DIR=/app/uploads
MAIL_TRANSPORT=local
MAIL_FROM=noreply@claper.co
MAIL_FROM_NAME=Claper
ELIXIR_ERL_OPTIONS=+fnu
EOF
chmod 600 .env

要点：

SECRET_KEY_BASE 必须每次部署新生成（官方 README 特别警告不要沿用示例值，否则可伪造 admin 会话 cookie）；
BASE_URL 决定应用对外自报地址与 LiveView WebSocket 回连地址，公网部署改为 https://claper.example.com 并配合反代；
ELIXIR_ERL_OPTIONS=+fnu 用于修复 Erlang VM 默认 latin1 文件名编码导致的中文乱码/警告问题（不加会怎样见 11.2 实录）。

4.3 拉取镜像

cd /opt/claper && docker compose pull

实测回显（节选）：

 Image ghcr.io/claperco/claper:3.2.0 Pulling 
 Image postgres:15 Pulling 
 Image postgres:15 Pulled 
 ...
 Image ghcr.io/claperco/claper:3.2.0 Pulled

⚠️ 若写成 ghcr.io/claperco/claper:v3.2.0（带 v）会报 failed to resolve reference ... not found，容器镜像标签规律见「二、镜像选型说明」与 11.1。

4.4 启动并等待健康

docker compose up -d

实测回显（节选）：

 Network claper-320-stack_claper-net Creating 
 Volume claper-320-stack_claper-db Creating 
 Volume claper-320-stack_claper-uploads Creating 
 Container claper-3.2.0-db Creating 
 Container claper-3.2.0-app Creating 
 Container claper-3.2.0-db Started 
 Container claper-3.2.0-db Waiting 
 Container claper-3.2.0-db Healthy 
 Container claper-3.2.0-app Started

docker compose ps

NAME               IMAGE                           COMMAND                  SERVICE   CREATED          STATUS                    PORTS
claper-3.2.0-app   ghcr.io/claperco/claper:3.2.0   "sh -c '/app/bin/cla…"   app       39 seconds ago   Up 8 seconds (healthy)    0.0.0.0:8129->4000/tcp, [::]:8129->4000/tcp
claper-3.2.0-db    postgres:15                     "docker-entrypoint.s…"   db        39 seconds ago   Up 38 seconds (healthy)   5432/tcp

4.5 验证启动日志（迁移与监听）

docker compose logs app | head -12

实测回显（节选，首次启动自动执行 Ecto 迁移）：

claper-3.2.0-app  | 10:30:32.007 [info] == Running 20211007130631 Claper.Repo.Migrations.CreateUsersAuthTables.change/0 forward
claper-3.2.0-app  | 10:30:32.011 [info] execute "CREATE EXTENSION IF NOT EXISTS citext"
claper-3.2.0-app  | 10:30:32.019 [info] execute "CREATE EXTENSION IF NOT EXISTS pgcrypto"
claper-3.2.0-app  | 10:30:32.023 [info] create table users
claper-3.2.0-app  | 10:30:32.029 [info] create table users_tokens
claper-3.2.0-app  | 10:30:32.037 [info] == Migrated 20211007130631 in 0.0s

docker compose logs app | tail -6

claper-3.2.0-app  | Global settings seeded
claper-3.2.0-app  | 10:30:34.554 [info] Running ClaperWeb.Endpoint with cowboy 2.19.0 at 0.0.0.0:4000 (http)
claper-3.2.0-app  | 10:30:34.555 [info] Access ClaperWeb.Endpoint at http://localhost:8129
claper-3.2.0-app  | 10:30:34.576 [info] {"message":"peer became leader","node":"claper@32122dd43d63","source":"oban","event":"peer:election","leader":true,"was_leader":false}

看到 Running ClaperWeb.Endpoint with cowboy ... at 0.0.0.0:4000 与 Access ... at http://localhost:8129（取自 BASE_URL）即启动成功；Global settings seeded 表示 global_configs 表已写入默认配置、种子管理员已创建。

4.6 HTTP 验证与登录实测

curl -sI http://localhost:8129 | head -4

HTTP/1.1 200 OK
cache-control: max-age=0, private, must-revalidate
content-length: 6093
content-type: text/html; charset=utf-8

Phoenix 登录接口带 CSRF 防护，可完整用 curl 走通验证：

CSRF=$(curl -s -c jar.txt http://localhost:8129/users/log_in \
  | grep -oE '<input name="_csrf_token"[^>]*value="[^"]+"' | grep -oE 'value="[^"]+"' | head -1 | cut -d'"' -f2)
curl -s -b jar.txt -c jar.txt -o /dev/null -w "LOGIN_HTTP=%{http_code} REDIRECT=%{redirect_url}\n" \
  -X POST http://localhost:8129/users/log_in \
  --data-urlencode "user[email]=admin@claper.co" \
  --data-urlencode "user[password]=claper" \
  --data-urlencode "user[remember]=true" \
  --data-urlencode "_csrf_token=$CSRF"
curl -s -b jar.txt -o /dev/null -w "EVENTS_HTTP=%{http_code}\n" http://localhost:8129/events

实测回显：

LOGIN_HTTP=302 REDIRECT=http://localhost:8129/events
EVENTS_HTTP=200

⚠️ 表单字段名必须是 user[email]/user[password]（Phoenix changeset 嵌套参数），直接传 email=/password= 会得到 403；这也是初次 curl 验证时实测踩过的坑。

浏览器路径等价：访问 http://<服务器IP>:8129/users/log_in，用 admin@claper.co / claper 登录后进入事件列表页。

4.7 修改默认密码（必做）

登录后进入 用户设置 → 修改密码，将默认口令改为 q1w2e3r4（示例演示账号）。改密也可走服务器端 release RPC，见《Claper 3.2.0 常用 CLI 命令与工具详解》（发布后补链）第 5.3 节实录。

4.8 创建演示事件与观众页验证

Web 界面：事件列表 → New event → 上传 PDF/PPTX（服务端自动转换为逐页幻灯片）→ 得到 5–10 位活动码；观众手机访问 http://<服务器IP>:8129/e/<活动码> 加入。

服务器端验证观众页路由（/e/:code 为观众视图，/e/:code/presenter 为演示者视图）：

curl -s -o /dev/null -w "E_DEMO01_HTTP=%{http_code}\n" http://localhost:8129/e/demo01

E_DEMO01_HTTP=200

⚠️ 若事件尚未关联演示文稿（未上传 PDF），观众页会返回 500，日志报 (KeyError) key :presentation_state not found in: nil——属预期行为，先给事件上传讲稿即可，详见 11.3。

五、数据持久化说明

数据	容器内路径	持久化载体	说明
PostgreSQL 数据	`/var/lib/postgresql/data`	命名卷 `claper-db`	用户、事件、投票、消息、Oban 作业全在此
幻灯片转换产物	`/app/uploads`	命名卷 `claper-uploads`	PDF/PPTX 转出的逐页图片与缩略图

卷随 docker compose down 默认保留；down -v 会删卷（数据丢失），操作前确认；
需要把数据落到宿主机目录（便于备份/rsync）时，可把两处 volumes: 改为 bind mount，例如 - /opt/claper/data/db:/var/lib/postgresql/data 与 - /opt/claper/data/uploads:/app/uploads（宿主机目录先 mkdir -p 并保持属主可写）；
备份口径：pg_dump 导出数据库 + 打包 uploads 目录，命令实测见《CLI 命令与工具详解》篇第 7 章。

六、环境变量表

.env 全量键（来源：官方仓库 v3.2.0 .env.sample，本地实测生效项标注 ✅）：

变量	默认/示例值	说明
`BASE_URL` ✅	`http://localhost:8129`	应用对外基地址，LiveView WebSocket 回连与邮件链接均用它
`DATABASE_URL` ✅	`postgres://claper:claper@db:5432/claper`	PostgreSQL 连接串
`SECRET_KEY_BASE` ✅	`openssl rand -base64 48` 生成	Phoenix 会话签名密钥，泄露=可伪造登录 cookie
`SAME_SITE_COOKIE` / `SECURE_COOKIE`	`Lax` / `false`	跨站 Cookie 策略；公网 HTTPS 建议 `Secure`/`true`
`PRESENTATION_STORAGE` ✅	`local`	`local` 或 `s3`
`PRESENTATION_STORAGE_DIR` ✅	`/app/uploads`	local 存储目录
`MAX_FILE_SIZE_MB`	`15`	上传讲稿大小上限
`S3_ACCESS_KEY_ID` 等 `S3_*`	注释示例	S3 兼容存储凭据/桶/端点/公开 URL
`MAIL_TRANSPORT` ✅	`local`	`smtp` / `postmark` / 其他=本地不发送
`MAIL_FROM` / `MAIL_FROM_NAME` ✅	`noreply@claper.co` / `Claper`	发件人
`SMTP_*`	注释示例	中继、端口、认证、TLS 等
`POSTMARK_API_KEY`	注释示例	Postmark 通道
`ENABLE_MAILBOX_ROUTE` / `MAILBOX_USER` / `MAILBOX_PASSWORD`	`false`/`admin`/`admin`	dev mailbox 邮件预览路由
`ENABLE_ACCOUNT_CREATION`	`true`	关闭自助注册设 `false`
`EMAIL_CONFIRMATION`	`true`	注册邮箱验证
`ALLOW_UNLINK_EXTERNAL_PROVIDER`	`false`	是否允许解绑外部登录
`LOGOUT_REDIRECT_URL`	无	登出后跳转
`GS_JPG_RESOLUTION`	`300x300`	幻灯片缩略图分辨率
`LANGUAGES`	全部	逗号分隔启用界面语言
`TERMS_URL` / `PRIVACY_URL`	无	注册页法务链接（两者都设才显示）
`REMOTE_IP_PROXIES` / `REMOTE_IP_HEADERS`	无	反代信任 IP/CIDR 与取真实 IP 的头列表
`OIDC_*`（PROVIDER_NAME/ISSUER/CLIENT_ID/CLIENT_SECRET/SCOPES/LOGO_URL/PROPERTY_MAPPINGS/AUTO_REDIRECT_LOGIN/TRUST_EMAIL_VERIFIED）	注释示例	OpenID Connect SSO
`DISABLE_PASSWORD_LOGIN`	无	`true` 时仅 OIDC 登录（启用前须先绑定并提升 OIDC 管理员，否则连种子 admin 都进不去）
`ELIXIR_ERL_OPTIONS` ✅	`+fnu`	非官方示例键：Erlang VM UTF-8 文件名编码开关，中文环境必加（见 11.2）

逐项深入说明（取值影响与生产模板）见《Claper 3.2.0 配置参数详解》（发布后补链）。

七、配置参数说明

Claper 的配置分三层，优先级与生效方式不同：

.env 环境变量（本章主体）：进程级配置，改后 docker compose up -d 重建 app 生效；
global_configs 数据库表：管理面板「设置」页写入的运行时配置（如 lti_enabled、transcription_api_key、transcription_enabled、transcription_default_language），实测查询：

docker compose exec db psql -U claper -d claper -c "SELECT key, value FROM global_configs ORDER BY key LIMIT 10;"

              key               | value 
--------------------------------+-------
 lti_enabled                    | false
 transcription_api_key          | 
 transcription_default_language | 
 transcription_enabled          | false
(4 rows)

每事件配置：事件级开关（聊天开关、匿名提问、置顶过滤等）在管理视图内逐事件设置，存于事件相关表。

三层参数的完整清单与修改方式在《配置参数详解》篇展开。

八、配置文件挂载

本方案的应用级配置只有一个文件：.env（经 compose env_file: 注入，compose 解析时读取，不需要挂载进容器）。若希望改 .env 后不重建容器也能审计文件内容，可将其只读 bind 进容器备用（非必需）：

    volumes:
      - "claper-uploads:/app/uploads"
      - "./.env:/app/.env:ro"   # 仅审计留档用，进程实际读的是 env_file 注入值

PostgreSQL 侧如需自定义参数（连接数、内存），可挂载 postgresql.conf 覆盖：

    volumes:
      - "claper-db:/var/lib/postgresql/data"
      - "./postgres_extra.conf:/etc/postgresql/postgresql.conf:ro"

并在 db 服务加 command: -c config_file=/etc/postgresql/postgresql.conf。默认 postgres:15 开箱参数即可支撑中小规模活动，非调优场景不建议动。

九、等价 docker run

compose 拆成手工命令等价如下（先建网络与卷）：

docker network create --subnet 10.89.56.0/24 claper-net
docker volume create claper-db
docker volume create claper-uploads

docker run -d --name claper-3.2.0-db --network claper-net \
  -v claper-db:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=*** -e POSTGRES_USER=claper -e POSTGRES_DB=claper \
  postgres:15

# 等待 pg_isready 通过后再起 app
docker run -d --name claper-3.2.0-app --network claper-net \
  -p 8129:4000 \
  -v claper-uploads:/app/uploads \
  -e BASE_URL=http://localhost:8129 \
  -e DATABASE_URL=postgres://claper:claper@claper-3.2.0-db:5432/claper \
  -e SECRET_KEY_BASE="$(openssl rand -base64 48)" \
  -e PRESENTATION_STORAGE=local -e PRESENTATION_STORAGE_DIR=/app/uploads \
  -e MAIL_TRANSPORT=local -e MAIL_FROM=noreply@claper.co -e MAIL_FROM_NAME=Claper \
  -e ELIXIR_ERL_OPTIONS=+fnu \
  ghcr.io/claperco/claper:3.2.0

差异点：手工形态没有 depends_on 健康门控，需自行确认 pg_isready 通过再起 app（否则迁移失败退出）；也没有 compose 的 healthcheck 声明，探活需手动 curl。生产仍推荐 compose 编排。

十、常用运维命令

cd /opt/claper

docker compose ps                    # 服务与健康状态
docker compose logs -f app           # 跟踪应用日志（Phoenix 请求日志含 request_id 与耗时）
docker compose restart app           # 重启应用（迁移不重跑）
docker compose up -d                 # .env 或 compose 改动后重建生效
docker compose exec app /app/bin/claper version    # 应用版本
docker compose exec db psql -U claper -d claper    # 进数据库

docker compose exec app /app/bin/claper version 实测回显：

claper 3.2.0

release 管理脚本（bin/claper 的 rpc/eval/pid/remote 等）与数据库备份恢复的完整实测见《Claper 3.2.0 常用 CLI 命令与工具详解》（发布后补链）。

十一、常见问题

11.1 拉镜像报 `failed to resolve reference "ghcr.io/claperco/claper:v3.2.0": ... not found`

现象：按 GitHub Release 名写 v3.2.0 标签，pull 直接失败：

 Image ghcr.io/claperco/claper:v3.2.0 Error failed to resolve reference "ghcr.io/claperco/claper:v3.2.0": ghcr.io/claperco/claper:3.2.0: not found
Error response from daemon: failed to resolve reference "ghcr.io/claperco/claper:v3.2.0": ghcr.io/claperco/claper:v3.2.0: not found

定位：匿名 token 查 registry 标签清单（见「二」），发现镜像标签是 3.2.0 数字形态，无 v 前缀。解决：image: ghcr.io/claperco/claper:3.2.0。GitHub Release 名与容器标签不同名是本项目惯例，升级时以 tags/list 为准。

11.2 日志刷 `native name encoding of latin1` 警告，且中文事件名入库变乱码字节串

现象：首次启动日志第一行：

warning: the VM is running with native name encoding of latin1 which may cause Elixir to malfunction as it expects utf8. Please ensure your locale is set to UTF-8 (which can be verified by running "locale" in your shell) or set the ELIXIR_ERL_OPTIONS="+fnu" environment variable

更实质的后果：通过 RPC 创建中文名事件，changeset 里名字变成双重编码字节串（<<68, 101, 109, 111, 32, 195, 164, 194, 186, ...>>）。

定位：Erlang VM 的 filename_decode 默认按运行环境 locale 决定，容器内 locale 非 UTF-8 → VM 以 latin1 处理外部输入，UTF-8 字节被逐字节重编码。解决：.env 加 ELIXIR_ERL_OPTIONS=+fnu 后重建 app：

echo 'ELIXIR_ERL_OPTIONS=+fnu' >> .env && docker compose up -d app

实测复核：重建后 docker compose logs app --since 30s | grep -c "native name encoding" 输出 0；再次创建中文名事件，入库为正确的 "中文事件测试"（RPC 回显 name: "\x{4E2D}\x{6587}\x{4E8B}\x{4EF6}\x{6D4B}\x{8BD5}"）。

11.3 观众页 `/e/<code>` 返回 500，日志 `(KeyError) key :presentation_state not found in: nil`

现象：

claper-3.2.0-app  | 10:37:08.099 [error] ... Request: GET /e/demo01
** (exit) an exception was raised:
    ** (KeyError) key :presentation_state not found in: nil
        (claper 3.2.0) lib/claper_web/live/event_live/show.ex:55: ClaperWeb.EventLive.Show.mount/3

定位：事件记录已存在但还没有关联演示文稿（未上传 PDF/PPTX，或转换未创建 presentation_files/presentation_states 行），观众视图 mount 直接取 presentation_state 崩溃。解决：在管理视图给该事件上传讲稿并等待转换完成；正常业务流（先传 PDF 再分享活动码）不会触发。用脚本/接口预建事件时务必同时补演示文稿。

11.4 curl 模拟登录返回 403

现象：POST /users/log_in 传 email=/password= 得 HTTP=403。定位：Phoenix 表单参数为 changeset 嵌套命名，且必须携带页面内 _csrf_token。解决：字段用 user[email]/user[password]/user[remember]，并先 GET 登录页提取 _csrf_token（实测流程见 4.6，302→/events 200 为成功标志）。

11.5 `name: claper-3.2.0-stack` 为何资源前缀变成 `claper-320-stack_`

现象：up -d 回显创建的网络/卷名为 claper-320-stack_claper-net、claper-320-stack_claper-db。定位：Compose 项目名规范化规则会剔除 . 等非法字符（3.2.0 → 320），name: 字段声明值与资源前缀并不逐字相等。解决：属正常行为，无需处理；脚本里引用网络/卷名时以 docker network ls/docker volume ls 实际值为准，或改用不含点的项目名（如 claper-320-stack）保持一致。

十二、参考链接

官方自托管快速开始：https://docs.claper.co/self-hosting/quick-start.html （查询日期 2026-11-01）
官方配置参考：https://docs.claper.co/self-hosting/configuration.html （查询日期 2026-11-01）
官方升级文档：https://docs.claper.co/self-hosting/updating.html （查询日期 2026-11-01）
官方 compose 模板：https://github.com/ClaperCo/Claper/blob/v3.2.0/docker-compose.yml
官方环境变量样例：https://github.com/ClaperCo/Claper/blob/v3.2.0/.env.sample
镜像仓库：https://github.com/ClaperCo/Claper/pkgs/container/claper
站内：《Claper 介绍与选型指南》

Claper Docker Compose 部署指南

Claper Docker Compose 部署指南

一、环境信息

二、镜像选型说明

三、前置条件

四、部署步骤

4.1 创建项目目录与 compose 文件

4.2 生成 .env 环境变量文件

4.3 拉取镜像

4.4 启动并等待健康

4.5 验证启动日志（迁移与监听）

4.6 HTTP 验证与登录实测

4.7 修改默认密码（必做）

4.8 创建演示事件与观众页验证

五、数据持久化说明

六、环境变量表

七、配置参数说明

八、配置文件挂载

九、等价 docker run

十、常用运维命令

十一、常见问题

11.1 拉镜像报 failed to resolve reference "ghcr.io/claperco/claper:v3.2.0": ... not found

11.2 日志刷 native name encoding of latin1 警告，且中文事件名入库变乱码字节串

11.3 观众页 /e/<code> 返回 500，日志 (KeyError) key :presentation_state not found in: nil

11.4 curl 模拟登录返回 403

11.5 name: claper-3.2.0-stack 为何资源前缀变成 claper-320-stack_

十二、参考链接

11.1 拉镜像报 `failed to resolve reference "ghcr.io/claperco/claper:v3.2.0": ... not found`

11.2 日志刷 `native name encoding of latin1` 警告，且中文事件名入库变乱码字节串

11.3 观众页 `/e/<code>` 返回 500，日志 `(KeyError) key :presentation_state not found in: nil`

11.5 `name: claper-3.2.0-stack` 为何资源前缀变成 `claper-320-stack_`