Hi.Events v1.11.2 Docker Compose 部署指南

目标:使用官方 all-in-one 镜像在 Docker Compose 上从零部署 Hi.Events v1.11.2 活动票务平台,覆盖镜像选型、端口与子网规划、首启自动建表、管理员注册与登录验证、数据持久化、备份恢复与升级路径。全部命令与回显均在 Ubuntu 22.04(x86_64)+ Docker Com

Hi.Events票务自托管2026/10/23

Hi.Events v1.11.2 Docker Compose 部署指南

目标:使用官方 all-in-one 镜像在 Docker Compose 上从零部署 Hi.Events v1.11.2 活动票务平台,覆盖镜像选型、端口与子网规划、首启自动建表、管理员注册与登录验证、数据持久化、备份恢复与升级路径。全部命令与回显均在 Ubuntu 22.04(x86_64)+ Docker Compose v2 环境实测通过,实测栈在部署当天完成注册、售票、下单、Webhook 全链路验证。

一、环境信息

项目实测值
操作系统Ubuntu 22.04.5 LTS(x86_64)
Hi.Events 版本v1.11.2-beta(2026-10-21 发布的 v1 稳定线,本文以 v1.11.2 指代)
镜像daveearley/hi.events-all-in-one:v1.11.2-beta
数据库镜像postgres:17-alpine(官方 compose 同款)
缓存镜像redis:7-alpine(官方 compose 同款)
Compose 网络专用网络 hievents-1.11.2-net,显式子网 10.89.58.0/24
对外端口8129 -> 80(Web 入口,nginx 统一承接前端与 /api)
镜像体积压缩约 276MB,解压后约 1.47GB(Docker Hub 口径,2026-10-23 实查)
后端运行时PHP 8.3.36 + Laravel 12.34.0(镜像内实测)
进程托管镜像内 supervisord 托管 nginx / php-fpm / 队列 Worker / 调度器 / 前端 SSR 五个进程

二、镜像选型说明

官方在 Docker Hub 提供 daveearley/ 账号下两个部署形态(2026-10-23 实查):

镜像定位适用
hi.events-all-in-one前端 + 后端 + nginx + 队列 + 调度器单包,内置自动建表启动脚本,累计拉取 213,577 次,多架构 amd64/arm64快速部署、中小规模、单机一体
hi.events-frontend + hi.events-backend前后端分离(累计拉取分别为 10,879 / 6,609 次)生产推荐,独立扩缩容;backend 不内置自动建表,需自行执行迁移

本文实测采用 all-in-one 形态:单容器内由 supervisord 托管五个进程(实测进程清单):

PID   USER     TIME  COMMAND
    1 root      php /usr/bin/supervisord -c /etc/supervisord.conf
   64 www-data  php /app/backend/artisan queue:work --queue=default,webhook-queue --sleep=3 --tries=3 --timeout=60
   65 www-data  /bin/sh -c while true; do php /app/backend/artisan schedule:run --no-interaction; sleep 60; done
   66 root      nginx: master process /usr/sbin/nginx -g daemon off;
   67 root      node /usr/share/node_modules/yarn/bin/yarn.js start
   69 root      php-fpm: master process (/usr/local/etc/php-fpm.conf)
   93 root      /usr/bin/node /app/frontend/node_modules/.bin/cross-env NODE_ENV=production node server.js

版本标签选择:锁定 v1.11.2-beta,勿用 latest——Docker Hub latest 当前指向 v2.0.0-rc.3(候选版),生产部署应使用稳定线标签。

三、前置条件

3.1 系统与软件

  • Docker Engine 与 Docker Compose v2(docker compose version 可用);
  • 服务器具备外网拉取镜像能力(Docker Hub);
  • 磁盘余量 ≥ 5GB(镜像 1.47GB + 数据库数据 + 缓存)。

3.2 端口与网络规划

  • 对外端口:8129(如被占用可自行调整映射,见常见问题);
  • 专用 compose 网络 hievents-1.11.2-net,显式指定子网 10.89.58.0/24(多套栈共存时避免网段漂移冲突)。

3.3 密钥预生成

部署前先生成两个密钥(后续写入 .env):

# APP_KEY:base64 编码的 32 字节随机串
openssl rand -base64 32
# JWT_SECRET:不少于 32 字符的随机十六进制串
openssl rand -hex 32

四、部署步骤

4.1 目录与 .env 准备

# mkdir -p /opt/data/hi-events-v1.11.2/{pgdata,redisdata,backup} && cd /opt/data/hi-events-v1.11.2

注:本文实测工作目录为 /opt/data/quzuo/tmp/hi-events/compose,读者可按自身磁盘规划调整;数据目录(pgdata、redisdata)与备份目录(backup)建议与应用配置同层管理。

创建 .env(实测文件全文,密钥值须替换为自己的随机串):

APP_KEY=base64:Hqk3DmVc8pW2rTxN7yBjLsQaZeF0gUhIvOcMnSbKd1w=
JWT_SECRET=Xk9Pv2QmR7tWz4YbCfJhLsDgNnEaUuIo6MkPqSrTvXyB3dGf5Hj8Lz0Wc2Vn6Qp4
VITE_FRONTEND_URL=http://localhost:8129
VITE_API_URL_CLIENT=http://localhost:8129/api
VITE_API_URL_SERVER=http://localhost/api
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_123456789
VITE_APP_NAME=Hi.Events
LOG_CHANNEL=stderr
QUEUE_CONNECTION=redis
APP_CDN_URL=http://localhost:8129/storage
APP_FRONTEND_URL=http://localhost:8129
APP_DISABLE_REGISTRATION=false
APP_SAAS_MODE_ENABLED=false
APP_TRUSTED_PROXIES=*
API_DOCS_ENABLED=true
MAIL_MAILER=log
MAIL_DRIVER=log
MAIL_HOST=mail.local
MAIL_PORT=1025
MAIL_FROM_ADDRESS=test@example.com
MAIL_FROM_NAME="Hi Events"
FILESYSTEM_PUBLIC_DISK=public
FILESYSTEM_PRIVATE_DISK=local
POSTGRES_DB=hi-events
POSTGRES_USER=postgres
POSTGRES_PASSWORD=q1w2e3r4
STRIPE_PUBLIC_KEY=pk_test_123456789
STRIPE_SECRET_KEY=sk_test_123456789
STRIPE_WEBHOOK_SECRET=whsec_test_123456789
REDIS_HOST=redis
REDIS_PASSWORD=
REDIS_PORT=6379

提示:http://localhost:8129 须替换为实际访问地址(如 http://10.89.58.10:8129 或公网域名),它同时决定前端资源 URL、API 客户端地址与 CDN 路径;APP_DISABLE_REGISTRATION 在完成首个管理员注册前必须保持 false(置 true 后注册接口返回 403,实测回显见常见问题)。

4.2 compose 文件

创建 docker-compose.yml(与官方 docker/all-in-one/docker-compose.yml 同构,环境注入与挂载点为实测形态):

name: hievents-1.11.2-stack

services:
  hievents:
    image: daveearley/hi.events-all-in-one:v1.11.2-beta
    container_name: hievents-1.11.2-aio
    restart: unless-stopped
    ports:
      - "8129:80"
    environment:
      - VITE_FRONTEND_URL=${VITE_FRONTEND_URL}
      - VITE_API_URL_CLIENT=${VITE_API_URL_CLIENT}
      - VITE_API_URL_SERVER=${VITE_API_URL_SERVER}
      - VITE_STRIPE_PUBLISHABLE_KEY=${VITE_STRIPE_PUBLISHABLE_KEY}
      - VITE_APP_NAME=${VITE_APP_NAME}
      - LOG_CHANNEL=${LOG_CHANNEL}
      - QUEUE_CONNECTION=${QUEUE_CONNECTION}
      - APP_KEY=${APP_KEY}
      - APP_CDN_URL=${APP_CDN_URL}
      - APP_FRONTEND_URL=${APP_FRONTEND_URL}
      - JWT_SECRET=${JWT_SECRET}
      - APP_DISABLE_REGISTRATION=${APP_DISABLE_REGISTRATION}
      - APP_SAAS_MODE_ENABLED=${APP_SAAS_MODE_ENABLED}
      - APP_TRUSTED_PROXIES=${APP_TRUSTED_PROXIES}
      - API_DOCS_ENABLED=${API_DOCS_ENABLED}
      - MAIL_MAILER=${MAIL_MAILER}
      - MAIL_DRIVER=${MAIL_DRIVER}
      - MAIL_HOST=${MAIL_HOST}
      - MAIL_PORT=${MAIL_PORT}
      - MAIL_FROM_ADDRESS=${MAIL_FROM_ADDRESS}
      - MAIL_FROM_NAME=${MAIL_FROM_NAME}
      - FILESYSTEM_PUBLIC_DISK=${FILESYSTEM_PUBLIC_DISK}
      - FILESYSTEM_PRIVATE_DISK=${FILESYSTEM_PRIVATE_DISK}
      - DATABASE_URL=postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-secret}@postgres:5432/${POSTGRES_DB:-hi-events}
      - REDIS_HOST=redis
      - REDIS_PASSWORD=
      - REDIS_PORT=6379
      - STRIPE_PUBLIC_KEY=${STRIPE_PUBLIC_KEY}
      - STRIPE_SECRET_KEY=${STRIPE_SECRET_KEY}
      - STRIPE_WEBHOOK_SECRET=${STRIPE_WEBHOOK_SECRET}
      - WEBHOOK_QUEUE_NAME=webhook-queue
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - hievents-net

  redis:
    image: redis:7-alpine
    container_name: hievents-1.11.2-redis
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "redis-cli", "ping" ]
      interval: 10s
      timeout: 5s
      retries: 5
    volumes:
      - ./redisdata:/data
    networks:
      - hievents-net

  postgres:
    image: postgres:17-alpine
    container_name: hievents-1.11.2-postgres
    restart: unless-stopped
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-postgres} -d $${POSTGRES_DB:-hi-events}" ]
      interval: 10s
      timeout: 5s
      retries: 5
    environment:
      POSTGRES_DB: ${POSTGRES_DB:-hi-events}
      POSTGRES_USER: ${POSTGRES_USER:-postgres}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-secret}
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    networks:
      - hievents-net

networks:
  hievents-net:
    name: hievents-1.11.2-net
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.58.0/24

4.3 拉起栈

# docker compose up -d
[+] Running 33/33
 ✔ hievents 23 layers [⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿]      0B/0B      Pulled
   ✔ a0d0a0d46f8b Pull complete
   ...
 ✔ Network hievents-1.11.2-net   Created
 ✔ Container hievents-1.11.2-redis    Healthy
 ✔ Container hievents-1.11.2-postgres Healthy
 ✔ Container hievents-1.11.2-aio      Started

约 30~60 秒后三服务全部进入 healthy(实测 docker compose ps):

# docker compose ps
NAME                     IMAGE                                          COMMAND                  SERVICE    CREATED          STATUS                    PORTS
hievents-1.11.2-aio      daveearley/hi.events-all-in-one:v1.11.2-beta   "docker-php-entrypoi…"   hievents   12 minutes ago   Up 12 minutes (healthy)   0.0.0.0:8129->80/tcp
hievents-1.11.2-postgres postgres:17-alpine                             "docker-entrypoint.s…"   postgres   52 minutes ago   Up 52 minutes (healthy)   5432/tcp
hievents-1.11.2-redis    redis:7-alpine                                 "docker-entrypoint.s…"   redis      52 minutes ago   Up 52 minutes (healthy)   6379/tcp

4.4 首启自动建表与启动脚本

all-in-one 镜像入口执行 /startup.sh(实测读取脚本原文):

cd /app/backend

if ! php artisan migrate --force; then
    echo "============================================"
    echo "ERROR: Migrations could not complete. Check the error above."
    echo "Ensure DATABASE_URL is set."
    echo "============================================"
fi

php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan storage:link

chown -R www-data:www-data /app/backend
chmod -R 775 /app/backend/storage /app/backend/bootstrap/cache

exec /usr/bin/supervisord -c /etc/supervisord.conf

要点:自动 migrate --force 建全部 102 张迁移记录(含 pg_trgm 扩展,迁移脚本自带 CREATE EXTENSION IF NOT EXISTS pg_trgm)、清各类缓存、接软链,随后交给 supervisord。迁移失败时日志会出现 Ensure DATABASE_URL is set. 提示,按常见问题排查。

4.5 注册管理员与登录验证

浏览器访问 http://<服务器IP>:8129/,点击注册创建首个管理员账号(实测账号 admin@example.com / q1w2e3r4)。命令行验证登录与 Web 入口(实测回显):

# curl -s -o /dev/null -w 'GET / -> %{http_code}\n' http://localhost:8129/
GET / -> 200

# curl -s -X POST http://localhost:8129/api/auth/login \
    -H 'Accept: application/json' -H 'Content-Type: application/json' \
    -d '{"email":"admin@example.com","password":"q1w2e3r4"}'
{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0L2F1dGgvbG9naW4iLCJpYXQiOjE3OTI3NTAwNzcsImV4cCI6MTc5MzM1NDg3NywibmJmIjoxNzkyNzUwMDc3LCJqdGkiOiJZNnBoR21UTHlBclpBT2ZlIiwic3ViIjoiMSIsInBydiI6ImI1YjFhZjFhZWY1MWUyMmU1Y2JlMzk0YzM3NDU3MjJhYjgwYWQ2Y2MiLCJhY2NvdW50X2lkIjoxLCJyb2xlIjoiQURNSU4ifQ.dTjNLiJeGk2TCFjUSiA6iJunXHjsGc-ADRicTXrymQI","token_type":"bearer","expires_in":604800}

expires_in=604800 即 JWT 有效期 7 天。登录后即可创建组织者与活动(实测创建 Demo Organizer / Demo Conference 2026,API 全流程实操见本专栏《Hi.Events v1.11.2 API 使用详解》)。

五、数据持久化说明

数据落点说明
PostgreSQL 业务数据./pgdata -> /var/lib/postgresql/data组织者/活动/票务产品/订单/购票人/用户全部在此,必须持久化
Redis 数据./redisdata -> /data队列与缓存;队列消息短暂堆积可容忍丢失,持久化可减少重建等待
密钥类(APP_KEY / JWT_SECRET).env 文件改密钥等于换库:APP_KEY 变化会导致加密数据不可解,JWT 全部失效
公共存储镜像内 /app/backend/storage/app/public海报等上传文件在 all-in-one 形态下位于容器层;长期生产建议改用分离镜像并外挂该目录或对接 S3(FILESYSTEM_PUBLIC_DISK=s3)

5.1 重启演练(实测)

docker compose restart 与整栈 down/up 各演练一次:

  • 重启后 /startup.sh 再次执行 migrate --force,日志输出 INFO Nothing to migrate.(表与数据都在挂载目录,迁移幂等跳过),随后 The [public/storage] link has been connected to [storage/app/public].;
  • 整栈 down/up 后登录态保持:此前签发的 JWT 仍可用(APP_KEY/JWT_SECRET 未变),活动与订单数据完整存活。

5.2 什么情况会丢数据

仅删除 pgdata/redisdata 目录或改用无名卷会丢业务数据;仅重建 hievents 服务不丢数据(数据库独立服务存在)。

六、环境变量表

实测 .env 全量键位与用途(镜像 v1.11.2 实际消费):

键实测值用途必改
APP_KEYbase64:...(openssl rand -base64 32)Laravel 应用密钥,加密列与签名✅
JWT_SECRET64 位十六进制API 认证令牌签名✅
VITE_FRONTEND_URL / APP_FRONTEND_URLhttp://<主机>:8129前端资源与页面 URL✅
VITE_API_URL_CLIENThttp://<主机>:8129/api浏览器侧 API 地址✅
VITE_API_URL_SERVERhttp://<主机>/apiSSR 服务端拉取 API 地址✅
APP_CDN_URLhttp://<主机>:8129/storage静态资源/上传文件前缀✅
VITE_APP_NAMEHi.Events站点名称展示可选
LOG_CHANNELstderr日志通道(容器形态 stderr 便于统一收集)可选
QUEUE_CONNECTIONredis队列驱动,必为 redis保持
APP_DISABLE_REGISTRATIONfalse关闭公开注册(首个管理员注册后可置 true,实测置 true 后注册返回 403)可选
APP_SAAS_MODE_ENABLEDfalseSaaS 多租户模式开关(商用授权场景)保持 false
APP_TRUSTED_PROXIES*反代场景透传客户端 IP按需
API_DOCS_ENABLEDtrueAPI 文档开关;v2 线特性键,v1.11.2 后端未引用(实测置 false 后 /docs/api 仍 200,仅是前端壳)可选
MAIL_MAILER / MAIL_DRIVERlog邮件驱动;生产改 smtp 并配 MAIL_HOST/PORT/USERNAME/PASSWORD可选
MAIL_FROM_ADDRESS / MAIL_FROM_NAMEtest@example.com / Hi Events发件人生产必改
FILESYSTEM_PUBLIC_DISK / FILESYSTEM_PRIVATE_DISKpublic / local存储盘;生产可切 s3可选
POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORDhi-events / postgres / 自设数据库三元组,同时拼接进 DATABASE_URL✅(密码)
REDIS_HOST / REDIS_PASSWORD / REDIS_PORTredis / 空 / 6379缓存与队列保持
STRIPE_PUBLIC_KEY / STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRETpk/sk/whsec 测试值Stripe 支付三件套;不开在线收款可留测试值(免费票不受影响)收款时必改
VITE_STRIPE_PUBLISHABLE_KEYpk_test_...前端 Stripe 公钥收款时必改
WEBHOOK_QUEUE_NAMEwebhook-queueWebhook 专用队列名(compose 内固定值,Worker 同时消费 default 与该队列)保持

七、配置参数说明

  • DATABASE_URL 拼接规则:compose 内由 POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB 拼成 postgresql://user:pass@postgres:5432/hi-events,其中 postgres 是服务名(网络内别名),改服务名需同步改连接串;
  • 依赖编排:hievents 服务 depends_on 带 condition: service_healthy,postgres 与 redis 未通过健康检查前不会启动应用,首启顺序无需人工干预;
  • 健康检查口径:postgres 用 pg_isready,redis 用 redis-cli ping,hievents 自带 HTTP 健康探针(状态列 healthy);
  • 时区:应用展示时区跟随数据与时区配置项,宿主机时区不影响订单时间戳存储(UTC 基准)。

八、配置文件挂载

all-in-one 形态的配置全部通过环境变量注入,无需挂载配置文件。镜像内部关键路径(实测):

路径内容
/app/backendLaravel 后端(含 .env 由环境变量渲染)
/app/frontendReact 前端构建产物与 SSR 入口 server.js
/etc/supervisord.conf五进程托管定义(nginx/php-fpm/nodejs/laravel-queue-worker/laravel-scheduler)
/startup.sh自动迁移与缓存清理入口脚本
/etc/nginx/...内置 nginx 站点配置(/api 前缀 rewrite 到 index.php,其余走前端)

如需深度定制 nginx 或分别扩缩容,改用官方分离镜像 hi.events-frontend + hi.events-backend(backend 需自行执行 php artisan migrate --force)。

九、等价 docker run 形态

不用 compose 时的等价手工编排(同一网络、同一挂载,实测口径一致):

# 1) 专用网络(显式子网)
docker network create --driver bridge --subnet 10.89.58.0/24 hievents-1.11.2-net

# 2) PostgreSQL
docker run -d --name hievents-1.11.2-postgres \
  --network hievents-1.11.2-net \
  -e POSTGRES_DB=hi-events -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=q1w2e3r4 \
  -v /opt/data/hi-events-v1.11.2/pgdata:/var/lib/postgresql/data \
  --restart unless-stopped postgres:17-alpine

# 3) Redis
docker run -d --name hievents-1.11.2-redis \
  --network hievents-1.11.2-net \
  -v /opt/data/hi-events-v1.11.2/redisdata:/data \
  --restart unless-stopped redis:7-alpine

# 4) Hi.Events all-in-one(环境变量与 compose 4.1 的 .env 对应,此处列关键项)
docker run -d --name hievents-1.11.2-aio \
  --network hievents-1.11.2-net \
  -p 8129:80 \
  -e APP_KEY=base64:<你的APP_KEY> \
  -e JWT_SECRET=<你的JWT_SECRET> \
  -e APP_FRONTEND_URL=http://<主机>:8129 \
  -e VITE_FRONTEND_URL=http://<主机>:8129 \
  -e VITE_API_URL_CLIENT=http://<主机>:8129/api \
  -e VITE_API_URL_SERVER=http://<主机>/api \
  -e APP_CDN_URL=http://<主机>:8129/storage \
  -e DATABASE_URL=postgresql://postgres:q1w2e3r4@postgres:5432/hi-events \
  -e REDIS_HOST=redis -e REDIS_PORT=6379 \
  -e QUEUE_CONNECTION=redis -e LOG_CHANNEL=stderr \
  -e APP_DISABLE_REGISTRATION=false \
  --restart unless-stopped \
  daveearley/hi.events-all-in-one:v1.11.2-beta

生产仍建议 compose(健康检查编排与环境变量管理更省心)。

十、常用运维命令

10.1 日常启停与状态

# docker compose ps                      # 三服务健康状态
# docker compose stop hievents           # 仅停应用(数据库保留连接清理)
# docker compose start hievents          # 再启动
# docker compose down                    # 停并移除(数据目录保留,不丢数据)
# docker compose up -d                   # 重新拉起

10.2 日志查看

# docker compose logs -f hievents        # 应用与迁移日志(含 supervisord 启动序列)
# docker compose logs --tail 100 postgres

10.3 备份与恢复(实测演练)

备份(自定义格式,实测 223,725 字节):

# docker exec hievents-1.11.2-postgres pg_dump -Fc -U postgres hi-events > backup/hi-events-20261023.dump
# ls -l backup/hi-events-20261023.dump
-rw-r--r-- 1 root root 223725 10月 23 18:14 backup/hi-events-20261023.dump

恢复演练(删库重建后完整回灌,实测通过):

# docker compose stop hievents            # 必须先停应用,否则 DROP 报错(见常见问题)
# docker exec hievents-1.11.2-postgres psql -U postgres -c 'DROP DATABASE "hi-events";'
DROP DATABASE
# docker exec hievents-1.11.2-postgres psql -U postgres -c 'CREATE DATABASE "hi-events";'
CREATE DATABASE
# docker exec -i hievents-1.11.2-postgres pg_restore -U postgres -d hi-events < backup/hi-events-20261023.dump
# docker compose start hievents

恢复后验证(实测回显,数据完整):

# docker compose ps hievents --format '{{.Name}} {{.Status}}'
hievents-1.11.2-aio Up 12 seconds (healthy)
# 登录并查询:
恢复后 events: [(1, 'Demo Conference 2026', 'LIVE')]
恢复后 organizers: [(1, 'Demo Organizer')]

10.4 版本升级路径

  1. 备份:按 10.3 导出 pg_dump -Fc,同时备份 .env;
  2. 改镜像标签:docker-compose.yml 中 image: 改为目标 tag(如后续 v1 线新补丁版);
  3. docker compose up -d hievents 拉起新版,/startup.sh 自动执行增量迁移;
  4. 验证:docker compose logs hievents 观察迁移输出,登录后核对活动与订单;
  5. 回滚:改回旧 tag 拉起即可(跨大版本升级前务必先备份;v1 → v2 正式版发布后需按官方升级说明单独评估,不要直接跳)。

十一、常见问题(部署期实测)

Q1:DROP DATABASE "hi-events" 报 database is being accessed by other users

应用服务还在连接数据库。先 docker compose stop hievents 再执行删库,恢复流程见 10.3(实测踩坑后修正的顺序)。

Q2:注册接口返回 403 Account registration is disabled

.env 中 APP_DISABLE_REGISTRATION=true 时公开注册被关闭(实测回显:{"message":"Account registration is disabled","errors":[]},HTTP 403)。首个管理员尚未注册前保持 false;如需彻底关闭公开注册,先注册管理员再置 true 并 docker compose up -d hievents 重建生效。

Q3:迁移失败,日志出现 Ensure DATABASE_URL is set.

/startup.sh 的固定错误提示,说明后端连不上数据库:逐项核对 DATABASE_URL 拼接(用户/密码/服务名/库名)、postgres 是否 healthy(docker compose ps)、pgdata 目录属主是否正常。

Q4:8129 端口被占用

修改 compose 中 ports 映射(如 "8130:80"),并同步更新 .env 中 VITE_FRONTEND_URL、VITE_API_URL_CLIENT、APP_CDN_URL、APP_FRONTEND_URL 的端口部分,docker compose up -d hievents 重建生效——四个 URL 不一致会导致前端资源 404 或 API 跨域失败。

Q5:页面能打开但静态资源/海报 404

检查 APP_CDN_URL 是否带 /storage 后缀并与对外端口一致(all-in-one 内置 nginx 将 /storage 路由到后端公共存储)。

Q6:API_DOCS_ENABLED=false 后 /docs/api 仍返回 200

该键为 v2 线特性,v1.11.2 后端未引用;/docs/api 的 200 只是前端单页壳,不代表文档服务开启(实测确认)。

Q7:免费票能否不开 Stripe?

可以。免费票(FREE 价格类型)下单不触发支付链路;Stripe 三件套留测试值不影响免费票与后台管理功能(实测全流程基于免费票完成)。

十二、参考链接