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 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_KEY | base64:...(openssl rand -base64 32) | Laravel 应用密钥,加密列与签名 | ✅ |
| JWT_SECRET | 64 位十六进制 | API 认证令牌签名 | ✅ |
| VITE_FRONTEND_URL / APP_FRONTEND_URL | http://<主机>:8129 | 前端资源与页面 URL | ✅ |
| VITE_API_URL_CLIENT | http://<主机>:8129/api | 浏览器侧 API 地址 | ✅ |
| VITE_API_URL_SERVER | http://<主机>/api | SSR 服务端拉取 API 地址 | ✅ |
| APP_CDN_URL | http://<主机>:8129/storage | 静态资源/上传文件前缀 | ✅ |
| VITE_APP_NAME | Hi.Events | 站点名称展示 | 可选 |
| LOG_CHANNEL | stderr | 日志通道(容器形态 stderr 便于统一收集) | 可选 |
| QUEUE_CONNECTION | redis | 队列驱动,必为 redis | 保持 |
| APP_DISABLE_REGISTRATION | false | 关闭公开注册(首个管理员注册后可置 true,实测置 true 后注册返回 403) | 可选 |
| APP_SAAS_MODE_ENABLED | false | SaaS 多租户模式开关(商用授权场景) | 保持 false |
| APP_TRUSTED_PROXIES | * | 反代场景透传客户端 IP | 按需 |
| API_DOCS_ENABLED | true | API 文档开关;v2 线特性键,v1.11.2 后端未引用(实测置 false 后 /docs/api 仍 200,仅是前端壳) | 可选 |
| MAIL_MAILER / MAIL_DRIVER | log | 邮件驱动;生产改 smtp 并配 MAIL_HOST/PORT/USERNAME/PASSWORD | 可选 |
| MAIL_FROM_ADDRESS / MAIL_FROM_NAME | test@example.com / Hi Events | 发件人 | 生产必改 |
| FILESYSTEM_PUBLIC_DISK / FILESYSTEM_PRIVATE_DISK | public / local | 存储盘;生产可切 s3 | 可选 |
| POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD | hi-events / postgres / 自设 | 数据库三元组,同时拼接进 DATABASE_URL | ✅(密码) |
| REDIS_HOST / REDIS_PASSWORD / REDIS_PORT | redis / 空 / 6379 | 缓存与队列 | 保持 |
| STRIPE_PUBLIC_KEY / STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET | pk/sk/whsec 测试值 | Stripe 支付三件套;不开在线收款可留测试值(免费票不受影响) | 收款时必改 |
| VITE_STRIPE_PUBLISHABLE_KEY | pk_test_... | 前端 Stripe 公钥 | 收款时必改 |
| WEBHOOK_QUEUE_NAME | webhook-queue | Webhook 专用队列名(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/backend | Laravel 后端(含 .env 由环境变量渲染) |
/app/frontend | React 前端构建产物与 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 版本升级路径
- 备份:按 10.3 导出
pg_dump -Fc,同时备份.env; - 改镜像标签:
docker-compose.yml中image:改为目标 tag(如后续 v1 线新补丁版); docker compose up -d hievents拉起新版,/startup.sh自动执行增量迁移;- 验证:
docker compose logs hievents观察迁移输出,登录后核对活动与订单; - 回滚:改回旧 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 三件套留测试值不影响免费票与后台管理功能(实测全流程基于免费票完成)。
十二、参考链接
- 官方部署文档:https://hi.events/docs/getting-started/deploying
- 官方 all-in-one compose 参考:https://github.com/HiEventsDev/Hi.Events/blob/develop/docker/all-in-one/docker-compose.yml
- Docker Hub 镜像:https://hub.docker.com/r/daveearley/hi.events-all-in-one
- 本专栏关联篇章:《Hi.Events v1.11.2 介绍与选型指南》(https://www.quzuo.net/document/mY4H7fsfHEiI )《Ubuntu 22.04 安装 Hi.Events v1.11.2 指南》《Hi.Events v1.11.2 配置参数详解》《Hi.Events v1.11.2 API 使用详解》