Koillection 1.8.5 配置参数详解

目标：讲清 Koillection 1.8.5 全部配置参数——应用根目录 .env 里的 15 个环境变量（应用核心 / 数据库 / JWT / CORS 四组）与 PHP 运行时层参数（时区 / 内存 / 上传体积），逐项给出默认值、实测值、生效方式与验证命令。全文参数实测自 Debian 13 + PHP 8.5 + PostgreSQL 17 环境（2026-10-28），安装过程见 《Koillection 1.8.5 安装部署指南》，组件背景见 《Koillection 1.8.5 介绍与选型指南》。

一、参数体系总览

Koillection 的配置只有两层：应用层是仓库根目录的 .env 文件（Symfony 标准做法），运行时层是 PHP 自身的 ini 设置。1.8.5 源码 .env 模板按组件分段，全部变量如下表（取自 1.8.5 标签 .env 原文）：

官方构建（仓库 docker/entrypoint.sh）在这套 .env 之外还按环境变量写入 PHP 层的 date.timezone、memory_limit、upload_max_filesize、post_max_size、session.cookie_secure 五个 ini 参数（对应环境变量名 PHP_TZ、PHP_MEMORY_LIMIT、UPLOAD_MAX_FILESIZE、HTTPS_ENABLED），裸机部署时直接改 /etc/php/8.5/fpm/ 下的 ini 即可，见第六章。

生效方式：.env 与 ini 修改后都要重建应用缓存并重载 PHP-FPM。prod 环境的缓存重建实测回显：

cd /opt/koillection && php bin/console cache:clear

 [OK] Cache for the "prod" environment (debug=false) was successfully cleared.

⚠️ cache:clear 输出前后可能伴随 twig/deprecation 的 INFO 日志（实测有 Twig Filter "spaceless" is deprecated 通知），不影响结果，末尾出现 [OK] 即成功。重载 PHP-FPM 用 systemctl reload php8.5-fpm（每条命令一个单元）。

二、应用核心参数

2.1 APP_ENV——运行环境开关

Symfony 的环境名，取值 prod 或 dev。它决定三件事：错误页是否带调试堆栈、容器编译产物是否缓存、以及哪些 bundle 被激活。

两个实测要点：其一，源码模板默认 APP_ENV=dev，而按官方流程 composer install --no-dev 不安装 dev 依赖，两者组合会让 post-install 脚本在找 WebProfilerBundle 时崩溃（完整排障过程见 《Koillection 1.8.5 安装部署指南》第四章排障实录一），生产部署第一件事就是把它改成 prod；其二，验证当前生效值可直接看命令行横幅：

cd /opt/koillection && php bin/console --version

Symfony 8.0.13 (env: prod, debug: false)

env: prod, debug: false 即 APP_ENV=prod + APP_DEBUG=0 的联合确认。

2.2 APP_SECRET——应用密钥

Symfony 框架级密钥，用于 CSRF 令牌生成等密码学场景。模板默认为空，必须填一个 32 位以上随机串，生成方法：

openssl rand -hex 16

实测输出：

0f4a7c9d2a84b7e35c0a9d4f18e7b2c65a

（每次执行输出都不同，取其中一次填入 .env 即可；实测环境填的是 6f1c9d2a84b7e35c0a9d4f18e7b2c65a。）改动后 cache:clear 生效。该值泄露等于站点密码学体系裸奔，生产环境不要把真实值提交进代码仓库。

2.3 APP_SHARE_DIR——共享目录声明

模板默认 var/share（相对项目根，即 /opt/koillection/var/share）。实测在 1.8.5 源码 src/ 与 config/ 全量检索均未发现引用，属模板预留变量，保持默认即可；若未来版本启用分享文件类功能，此目录会成为落盘点，权限应与 var/ 一致（www-data 可写）。

2.4 APP_DEBUG——调试明细开关

1 开启调试明细（报错堆栈、profiler），0 关闭。与 APP_ENV 独立但通常成对配置：prod 取 0、dev 取 1。验证方式见 2.1 节的 --version 横幅。生产保持 0，调试接口暴露报错堆栈属于信息泄露面。

三、数据库参数（DB_* 七项）

3.1 七个参数逐项说明

DB_VERSION 是最容易踩坑的一个：模板写的是 15，但那只是「模板作者写文档时的版本示例」，装了 PostgreSQL 17 就要改成 17——1.8.4 升级说明里官方也强调了环境变量瘦身（不再依赖代理头变量），但 DB_VERSION 语义未变。

3.2 换 MySQL/MariaDB 的参数组合

官方 README 徽章标注支持 PostgreSQL ≥ 10、MySQL ≥ 8.0、MariaDB ≥ 10。切换只需要：安装 php8.5-mysql 扩展 → .env 改 DB_DRIVER=pdo_mysql + 对应 HOST/PORT/NAME/USER/PASSWORD → 重跑 php bin/console doctrine:migrations:migrate --no-interaction（迁移类会自动只执行 MySQL 方言那组）。本文实测基于 PostgreSQL，切换步骤未实测，以官方 Wiki 为准。

3.3 连通性验证与典型故障

参数改完先用一条命令做端到端验证（用与 .env 相同的口令实测）：

PGPASSWORD=koillection psql -h 127.0.0.1 -U koillection -d koillection -Atc "select 1;"

1

⚠️ 排障实录：FATAL: password authentication failed for user "koillection"。 实测 DB_PASSWORD 与数据库角色实际口令不一致时，任何走数据库的命令（含 doctrine:migrations:migrate、Web 页面）都会报：

connection to server at "localhost" (::1), port 5432 failed: FATAL:  password authentication failed for user "koillection"

定位三步：确认 .env 的 DB_USER/DB_PASSWORD → 用 PGPASSWORD=... psql -h 127.0.0.1 -U ... 复现 → 在 PostgreSQL 侧 ALTER USER 重设口令。修复实录见安装部署指南第四章排障实录二。

四、JWT 鉴权参数（API 通道）

4.1 三个参数

实测生成密钥对后 config/jwt/ 下有 config.pem、private.pem、public.pem 三个文件。JWT_PASSPHRASE 模板为空而生成命令要求非空口令，部署时先填 .env（本文用 koillection-lab）再执行生成，顺序不能反。

4.2 端到端实测：签发与鉴权

Koillection 的 API 登录端点是 /api/authentication_token（security.yaml 中 username_path: username，载荷字段用 username 而不是 email——实测用 email 提交会得到 {"status":400,"detail":"Bad Request"}）：

curl -s -X POST http://127.0.0.1:8143/api/authentication_token \
    -H "Content-Type: application/json" \
    -d '{"username":"admin","password":"q1w2e3r4"}' | head -c 120

实测回显（输出节选）：

{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE3OTMxODgyMzAsImV4cCI6MTc5MzE5MTgzMCwicm9sZXMiOlsiUk9MRV9VU0VSIiwiUk9MRV9BRE1JTiJdLCJ1c2VybmFtZSI6ImFkbWluIn0.cu1jTlQeHHulyIVRkR_mPukx0kS...

把 token 解开看头部与载荷：{"typ":"JWT","alg":"RS256"}、载荷含 iat/exp/roles/username，实测 iat 与 exp 相差 3600 秒——令牌有效期 1 小时（lexik 默认值）。拿它调受保护接口与匿名访问对比：

curl -s -o /dev/null -w "带令牌:%{http_code}\n" -H "Authorization: Bearer <上一步的token>" http://127.0.0.1:8143/api/users
curl -s -o /dev/null -w "匿名:%{http_code}\n" http://127.0.0.1:8143/api/users

实测回显：

带令牌:200
匿名:401

三项 JWT 参数改动后 cache:clear 生效；换密钥对时用 php bin/console lexik:jwt:generate-keypair --no-interaction 重新生成，所有已签发令牌立即失效（旧公钥验不过新签名），属预期行为。

五、CORS_ALLOW_ORIGIN——跨域白名单

控制 REST API 允许的跨域来源，模板默认正则只放行本机任意端口：

CORS_ALLOW_ORIGIN='^https?://(localhost|127\.0\.0\.1)(:[0-9]+)?$'

实测验证（OPTIONS 预检，Origin 为本机 5173 端口的前端开发服务器）：

curl -s -o /dev/null -D - -X OPTIONS -H "Origin: http://localhost:5173" \
    -H "Access-Control-Request-Method: GET" http://127.0.0.1:8143/api | grep -i access-control

实测回显：

Access-Control-Allow-Methods: GET, OPTIONS, POST, PUT, PATCH, DELETE
Access-Control-Allow-Headers: content-type, authorization
Access-Control-Max-Age: 3600
Access-Control-Allow-Origin: http://localhost:5173

正则命中的 Origin 被原样回显进 Allow-Origin 头。若要自建前端（跑在其他域名）访问 API，把正则扩成 ^https?://(localhost|127\.0\.0\.1|你的域名)(:[0-9]+)?$ 后 cache:clear。这是纯 API 层参数，浏览器里的正常使用不受它影响。

六、PHP 运行时层参数

官方构建通过环境变量写入五个 PHP ini 参数（docker/entrypoint.sh 实录），裸机部署时对应关系与实测默认值如下：

实测 CLI 侧默认值回显：

php -i | grep -E "^(memory_limit|upload_max_filesize|post_max_size|date\.timezone|session\.cookie_secure)"

memory_limit => -1 => -1
post_max_size => 8M => 8M
upload_max_filesize => 2M => 2M
date.timezone => UTC => UTC
session.cookie_secure => Off => Off

三点解读：上传体积是实际影响最大的——裸机默认 upload_max_filesize=2M，而条目照片常超 2M，按官方构建的 20M 对齐即可（在 /etc/php/8.5/fpm/conf.d/ 下新建 99-koillection.ini 写入 upload_max_filesize = 20M 与 post_max_size = 100M，systemctl reload php8.5-fpm 后用 phpinfo 页面或 php-fpm8.5 -i | grep upload_max_filesize 验证）；时区建议按部署地设置（如 Asia/Shanghai），影响条目日期展示与日志时间戳；memory_limit 官方给 512M，对小内存主机（1C1G）可下调到 256M——图片缩略图生成是内存大头，2M 级照片的 GD 解码约需数十 MB，512M 已很宽裕。

nginx 侧还有一个配套值：安装篇站点配置里的 client_max_body_size 32m（实测配置），需不小于 PHP 的 post_max_size，否则大图上传先被 nginx 挡下。

七、参数核对清单

改完任何参数，按这张清单核对一遍（全部命令实测可用）：

cd /opt/koillection
php bin/console --version                        # 看 env/debug 两项
grep -E "^APP_|^DB_|^JWT_|^CORS" .env            # 核对全部 .env 实值
php bin/console cache:clear                      # 重建缓存（.env 类参数生效）
php bin/console doctrine:migrations:status 2>/dev/null | grep -E "Storage|Executed" | head -3   # 数据库连通+迁移状态
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8143/api   # API 层连通

实测回显（第 4 条，输出节选）：

Storage
 Executed 68, 68 mig

迁移存储可读、68 条版本记录在案，说明数据库参数真实生效。

参考链接

1. 1.8.5 源码 .env 模板：https://github.com/koillection/koillection/blob/1.8.5/.env
2. 1.8.5 官方构建入口脚本（运行时参数来源）：https://github.com/koillection/koillection/blob/1.8.5/docker/entrypoint.sh
3. 官方配置 Wiki：https://github.com/koillection/koillection/wiki/Configuration
4. lexik JWT 包文档：https://github.com/lexik/LexikJWTAuthenticationBundle
5. 站内延伸：《Koillection 1.8.5 介绍与选型指南》、《Koillection 1.8.5 安装部署指南》、《Koillection 1.8.5 常用 CLI 命令与工具详解》