Hi.Events v1.11.2 配置参数详解

目标：系统梳理 Hi.Events v1.11.2 的全部配置参数。配置体系为 Laravel 标准 .env 环境变量注入：官方镜像 v1.11.2 的 config/*.php 实际消费 180 个环境键，本文逐组拆解用途与默认值，并对注册开关、API 限流、文档开关等待验证项给出实测回显。键位清单与生效行为均在 v1.11.2-beta 镜像与源码树上实测核对（2026-10-23）。

一、环境信息

二、前置条件

• 已按《Ubuntu 22.04 安装 Hi.Events v1.11.2 指南》或《Hi.Events v1.11.2 Docker Compose 部署指南》完成部署并可登录；
• 熟悉 Laravel 配置生效规则：.env 改动后必须清除配置缓存（或重建服务）才生效。

三、参数查看与修改方式

查看键位与默认值：直接检索后端 config/ 目录（镜像内路径 /app/backend/config/），实测命令：

# docker exec hievents-1.11.2-aio grep -n "disable_registration" /app/backend/config/app.php
    'disable_registration' => env('APP_DISABLE_REGISTRATION', false),

env('KEY', default) 的第二参数即默认值——未设置环境变量时生效的就是它。

修改方式（两种部署形态）：

官方 all-in-one 镜像启动时自动执行 cache:clear / config:clear / route:clear / view:clear（/startup.sh 实测原文见 B2 篇 4.4），因此 compose 形态改配置不需要手工清缓存。

验证生效：改动后用对应接口复测（如注册开关用注册接口、限流键连发请求看 429）。

四、参数总览

180 个环境键按配置文件归属分组统计（实测汇总）：

键位清单中包含少量当前版本已闲置或面向新版本的键（见 5.14 v2 键甄别），配置时以「实测有效」标注为准。

五、核心参数分类详解

5.1 应用基础（APP_*）

VITE_* 系列是前端构建期变量（VITE_FRONTEND_URL、VITE_API_URL_CLIENT、VITE_API_URL_SERVER、VITE_APP_NAME、VITE_STRIPE_PUBLISHABLE_KEY）：源码部署在 yarn build 前写入 frontend/.env；all-in-one 镜像在启动时注入并已预构建，改动后需重建服务才随环境生效。

5.2 注册与账号（实测）

实测建议：内部系统先 false 注册管理员 → 改 true 重建 → 验证 403。全流程回显见 B2 篇常见问题 Q2。

5.3 API 限流（实测）

限流实测：置 APP_API_RATE_LIMIT_PER_MINUTE=5 重建后连发 8 个未登录登录请求：

req1 -> 422    # 参数校验错误（仍计数）
req2 -> 422
req3 -> 422
req4 -> 422
req5 -> 422
req6 -> 429    # 触发限流
req7 -> 429
req8 -> 429

429 响应体（实测）：{"message": "Too Many Attempts."}。还原默认值后恢复 422（正常业务校验响应）。

5.4 数据库（DB_* / DATABASE_URL）

迁移自动创建 pg_trgm 扩展（database/migrations/extensions.sql：CREATE EXTENSION IF NOT EXISTS pg_trgm;），数据库账号需具备建扩展权限（属主账号即可）。

5.5 Redis（REDIS_*）

5.6 缓存 / 队列 / 会话

5.7 邮件（MAIL_*）

注意：MAIL_MAILER=log 时不真实发信，内容写入 storage/logs/laravel.log——验收邮件模板用它最方便，生产务必切 smtp。

5.8 文件存储（FILESYSTEM_* / AWS_*）

5.9 支付（STRIPE_*）

5.10 JWT 认证（JWT_*）

5.11 Webhook 与异步任务

5.12 监控与日志（SENTRY_* / LOG_*）

5.13 其他集成

5.14 v2 键甄别（避免无效配置）

• API_DOCS_ENABLED：v2 线特性键。v1.11.2 后端 config/ 与 routes/ 中 0 处引用（实测 grep）；置 false 后 /docs/api 仍返回 200——那只是前端单页壳，并非文档服务开关。v1 部署无需配置该键；
• 键位清单中 MYSQL_ATTR_SSL_CA、DB_ENCRYPT 等属于框架/兼容残留，pgsql 形态不生效；
• 升级 v2 后新增键（个人 API Key、SSO 等）以官方 v2 文档为准，不要提前写入生产 .env。

六、生产配置模板

以下为最小生产模板（标注 ✅ 的必须替换为自有值；场景：单机 4C8G、活动售票中型负载、邮件走外部 SMTP、存储本地盘）：

APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:<openssl rand -base64 32>            # ✅
JWT_SECRET=<openssl rand -hex 32>                   # ✅
APP_URL=http://events.example.com                   # ✅
APP_FRONTEND_URL=http://events.example.com          # ✅
VITE_FRONTEND_URL=http://events.example.com         # ✅
VITE_API_URL_CLIENT=http://events.example.com/api   # ✅
VITE_API_URL_SERVER=http://events.example.com/api   # ✅
APP_CDN_URL=http://events.example.com/storage       # ✅
LOG_CHANNEL=daily                                   # 容器形态用 stderr
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=hi-events
DB_USERNAME=hi_events
DB_PASSWORD=<强密码>                                 # ✅
CACHE_STORE=redis
CACHE_DRIVER=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis
SESSION_LIFETIME=120
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
MAIL_MAILER=smtp
MAIL_DRIVER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=<发信账号>                             # ✅
MAIL_PASSWORD=<发信密码>                             # ✅
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=no-reply@example.com
MAIL_FROM_NAME="Hi.Events"
APP_DISABLE_REGISTRATION=true                       # 管理员注册完成后再开
APP_API_RATE_LIMIT_PER_MINUTE=180                   # 按流量调整
FILESYSTEM_PUBLIC_DISK=public
FILESYSTEM_PRIVATE_DISK=local
STRIPE_PUBLIC_KEY=pk_live_xxx                       # 收款时配置
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx

磁盘规划：数据库 20GB 起（含订单与票务增长）、日志轮转 5GB、公共存储按海报量 10GB 起；APP_KEY/JWT_SECRET/数据库密码务必离线备份——密钥丢失等于业务数据作废。

七、常见问题

Q1：改了 .env 不生效

Laravel 配置有缓存。compose 形态 docker compose up -d hievents 重建（启动脚本自动清缓存）；源码形态 php artisan config:clear && systemctl reload php8.3-fpm，队列 Worker 另需重启。

Q2：REDIS_HOST=redis 报连接失败

redis 是 Docker 栈内的服务名。源码/本机部署写 localhost 或 127.0.0.1（B1 篇排障实录一）。

Q3：API_DOCS_ENABLED=false 后 /docs/api 仍 200

该键 v1.11.2 未引用（v2 特性），200 来自前端单页壳，属正常现象（实测确认）。

Q4：更换 APP_KEY 后会怎样

加密列数据不可解、全部 JWT 失效（需重新登录）、可能影响已存加密字段读取。仅在全新部署时生成一次，之后不再变更；如必须更换，先做数据库备份并评估加密列影响。

Q5：API 大量返回 429

触发了 APP_API_RATE_LIMIT_PER_MINUTE 限流（按用户 ID/IP 计数）。负载测试或集成调用前调大该值；429 响应体固定为 {"message": "Too Many Attempts."}（实测）。

Q6：邮件发不出去

先确认 MAIL_MAILER=smtp（log 只写日志不真实发信）；再核对 MAIL_FROM_ADDRESS 与 SMTP 供应商的发信域名一致性；内网自建 SMTP 若证书不受信，MAIL_VERIFY_PEER=false 临时放行（生产补正规证书）。

八、参考链接

• 官方部署文档（Environment Variables 章节）：https://hi.events/docs/getting-started/deploying
• 后端配置源码：https://github.com/HiEventsDev/Hi.Events/tree/develop/src/Config（v1.11.2 tag 对应 config/ 目录）
• 本专栏关联篇章：《Hi.Events v1.11.2 介绍与选型指南》《Ubuntu 22.04 安装 Hi.Events v1.11.2 指南》《Hi.Events v1.11.2 Docker Compose 部署指南》《Hi.Events v1.11.2 API 使用详解》