Koillection 1.8.5 安装部署指南

Debian 13 从零部署 Koillection 1.8.5 实测：Sury PHP 8.5 + PostgreSQL 17 + nginx 源码部署全流程，含 Composer 依赖、数据库迁移、前端构建、管理员初始化与四则排障实录。

KoillectionKoillectionPHP 编程NAS 自托管2026/10/28

Koillection 1.8.5 安装部署指南

目标：在一台 Debian 13 服务器上从零把 Koillection 1.8.5 跑起来：装齐 PHP 8.5 + PostgreSQL 17 + nginx，拉取 1.8.5 源码、安装 Composer 依赖、执行数据库迁移、构建前端静态资源、配置站点并完成管理员初始化。全文命令与回显均来自真实服务器实测（Debian 13，2026-10-28），组件背景与选型对比见 《Koillection 1.8.5 介绍与选型指南》。

一、部署前准备

1.1 版本选型与对照表

Koillection 1.8.5 是 PHP 单体全栈应用，官方对运行环境的要求与本文实测版本如下：

组件官方要求本文实测版本来源
操作系统无硬性要求Debian 13 (trixie)实测服务器
PHP≥ 8.5（composer.json 约束）8.5.12php -v 实测
数据库PostgreSQL ≥ 10 / MySQL ≥ 8.0 / MariaDB ≥ 10PostgreSQL 17.11psql --version 实测
Web 服务器任意（官方构建用内嵌 Caddy）nginx 1.26.3nginx -v 实测
PHP-FPM随 PHP 安装php-fpm 8.5（Unix socket）pool.d/www.conf 实测
Composer≥ 2.x2.10.3安装器实测输出
Node.js + yarnNode ≥ 26（assets/package.json engines），yarn 4.xNode v26.12.1 + yarn 4.15.0node -v 实测
Koillection—1.8.5（git 标签，commit 66b331a "Release 1.8.5"）git describe --tags 实测

关键差异说明：PHP 8.5 高于 Debian 13 官方仓库内置版本（trixie 官方源为 PHP 8.4，php8.5 包不存在），必须添加社区维护的 Sury PHP 源；Node ≥ 26 是 1.8.5 前端构建的硬约束（package.json engines 字段），低于该版本 yarn install 会拒绝执行。

1.2 系统初始更新

先更新软件源索引并安装基础工具（git 用于拉源码，unzip/xz-utils 用于解压，ca-certificates 保证 HTTPS 源可用）：

apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates curl gnupg2 lsb-release git unzip xz-utils procps sudo

实测回显（输出节选，实测末行）：

0 upgraded, 61 newly installed, 0 to remove and 0 not upgraded.

1.3 部署形态说明

本文采用「源码 + nginx + PHP-FPM + PostgreSQL」的传统部署形态：Koillection 是标准 Symfony 应用，PHP-FPM 承载 PHP 进程，nginx 只做静态资源与 FastCGI 转发，无需任何常驻应用进程管理工具。官方官方构建则把 PHP 解释器嵌入 Caddy（FrankenPHP 运行时），两种形态跑同一份代码，本文选择 nginx + PHP-FPM 是因为它只依赖 Debian 官方仓库与 Sury 源，组件全部来自 apt，升级与排查路径最通用。数据库层面，Koillection 通过 DB_DRIVER 环境变量切换 PostgreSQL/MySQL/MariaDB（官方 README 徽章标注 PG ≥ 10、MySQL ≥ 8.0、MariaDB ≥ 10），本文实测 PostgreSQL 17；如需换 MySQL，安装 php8.5-mysql 扩展并把 DB_DRIVER 改为 pdo_mysql 即可。

二、安装基础组件

2.1 添加 Sury PHP 源并安装 PHP 8.5

Debian 13 官方源没有 PHP 8.5，添加 Sury 源（Debian 社区最常用的 PHP 第三方源）后安装 Koillection 需要的全部 PHP 组件：

install -d /etc/apt/keyrings
curl -sSLo /etc/apt/keyrings/sury-php.gpg https://packages.sury.org/php/apt.gpg
echo "deb [signed-by=/etc/apt/keyrings/sury-php.gpg] https://packages.sury.org/php/ trixie main" \
    > /etc/apt/sources.list.d/sury-php.list
apt-get update
apt-get install -y --no-install-recommends \
    php8.5-fpm php8.5-cli php8.5-pgsql php8.5-gd php8.5-intl php8.5-apcu \
    php8.5-curl php8.5-zip php8.5-xml php8.5-mbstring php8.5-sqlite3 \
    postgresql nginx libatomic1

⚠️ 网络说明：packages.sury.org 为境外源，实测直连可用但拉取元数据较慢；实测源索引回显 Get:3 https://packages.sury.org/php trixie InRelease [6129 B]。若直连超时，可为 apt 配置代理（/etc/apt/apt.conf.d/proxy.conf 写入 Acquire::http::Proxy "http://192.168.1.62:7897";）后重试。

实测回显（输出节选，实测首尾）：

0 upgraded, 90 newly installed, 0 to remove and 0 not upgraded.
...
Setting up php8.5-pgsql (8.5.12-1+0~20261021.27+debian13~1.gbp1a3e8a) ...
Setting up php8.5-intl (8.5.12-1+0~20261021.27+debian13~1.gbp1a3e8a) ...
Setting up php8.5-cli (8.5.12-1+0~20261021.27+debian13~1.gbp1a3e8a) ...
Setting up php8.5-fpm (8.5.12-1+0~20261021.27+debian13~1.gbp1a3e8a) ...
Setting up php8.5-gd (8.5.12-1+0~20261021.27+debian13~1.gbp1a3e8a) ...
Creating new PostgreSQL cluster 17/main ...
Setting up nginx (1.26.3-3+deb13u10) ...

各 PHP 包用途：pgsql 提供 PostgreSQL 驱动（Koillection 数据库层必需）、gd 生成缩略图、intl 国际化格式化（Symfony 表单与 Twig 依赖）、apcu 本地缓存加速、curl/zip/xml/mbstring 是 composer.json 里声明的必备扩展。

安装完成后核对版本与扩展（三条验证命令及实测回显）：

php -v | head -1

PHP 8.5.12 (cli) (built: Oct 21 2026 08:09:42) (NTS)

psql --version

psql (PostgreSQL) 17.11 (Debian 17.11-0+deb13u1)

nginx -v

nginx version: nginx/1.26.3

⚠️ 上述 nginx/PostgreSQL/php-fpm 均为 apt 安装后自带的 systemd 单元；在有 systemd 的真机上用 systemctl enable --now nginx、systemctl enable --now php8.5-fpm、systemctl enable --now postgresql 逐个启用自启（每行一个单元）。

2.2 安装 Composer

用官方安装器脚本安装（安装器会校验 PHP 环境后下载 composer.phar）：

curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

实测回显：

Composer (version 2.10.3) successfully installed to: /tmp/composer-test
Use it: php /tmp/composer-test

⚠️ 网络说明：getcomposer.org 境外直连实测可用；若失败可先经代理下载安装器（https_proxy=http://192.168.1.62:7897 curl -sS https://getcomposer.org/installer | php）。安装器输出中的目标路径跟随 --install-dir 参数，装到 /usr/local/bin 时上述回显对应路径为 /usr/local/bin/composer。

2.3 安装 Node.js 26 与 yarn

前端构建要求 Node ≥ 26，用官方二进制包解压到 /usr/local：

curl -fsSL https://nodejs.org/dist/v26.12.1/node-v26.12.1-linux-x64.tar.xz \
    | tar -xJ -C /usr/local --strip-components=1
npm install -g corepack
corepack enable

⚠️ 网络说明：nodejs.org 直连下载在本环境实测失败（下载管道 exit code: 2），改用代理导出 tar 包后解压成功；读者在境外网络不畅时可先 https_proxy=http://192.168.1.62:7897 curl -fLo /tmp/node.tar.xz https://nodejs.org/dist/v26.12.1/node-v26.12.1-linux-x64.tar.xz 再 tar -xJf /tmp/node.tar.xz -C /usr/local --strip-components=1。URL 中的 v26.12.1 可按需换成 nodejs.org/dist 上的更新 26.x 版本。

yarn 无需单独安装：Koillection 的 assets/package.json 声明了 packageManager: yarn@4.15.0，corepack 会按该字段自动使用对应版本。验证：

node -v

v26.12.1

三、准备数据库

3.1 创建专用角色与数据库

PostgreSQL 17 安装时已初始化 17/main 集群。为 Koillection 创建专用角色和同名数据库（与本机 peer 认证配合，先以 postgres 系统用户执行）：

su postgres -c "createuser -S -D -R -l koillection"
su postgres -c "createdb -O koillection koillection"

再为该角色设置与后面 .env 一致的口令（本文演示用 koillection，生产环境请换强口令）：

su postgres -c "psql -c \"ALTER USER koillection WITH PASSWORD 'koillection';\""

实测回显：

ALTER ROLE

3.2 连通性验证

PGPASSWORD=koillection psql -h 127.0.0.1 -U koillection -d koillection -Atc "select version();" | head -1

PostgreSQL 17.11 (Debian 17.11-0+deb13u1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit

能取回服务器版本串即说明 TCP + 口令认证链路通畅，这一步能提前暴露 90% 的数据库连接问题（口令错、pg_hba 拒绝、监听地址不含 127.0.0.1）。

四、获取源码并安装后端依赖

4.1 下载 1.8.5 源码

从官方仓库拉取 1.8.5 标签（也可到 GitHub Releases 页面下载 Source code (tar.gz) 后解压到同一路径，效果一致）：

git clone -b 1.8.5 https://github.com/koillection/koillection.git /opt/koillection
cd /opt/koillection
git describe --tags

实测回显：

1.8.5

⚠️ 网络说明：GitHub 克隆速度不稳时可改用代理（git -c http.proxy=http://192.168.1.62:7897 clone ...）或镜像站。

4.2 配置 .env

应用级配置全部在项目根目录 .env 中。生产部署至少要改 5 处：环境切到 prod、生成随机 APP_SECRET、数据库四项、JWT 口令：

cd /opt/koillection
sed -i 's/^APP_ENV=dev/APP_ENV=prod/' .env
sed -i 's/^APP_DEBUG=1/APP_DEBUG=0/' .env
sed -i "s/^APP_SECRET=$/APP_SECRET=<32位随机串>/" .env
sed -i 's/^DB_VERSION=15/DB_VERSION=17/' .env
sed -i "s/^JWT_PASSPHRASE=$/JWT_PASSPHRASE=koillection-lab/" .env

说明：APP_SECRET 用 openssl rand -hex 16 生成一个真实值填入（实测环境为 6f1c9d2a84b7e35c0a9d4f18e7b2c65a）；DB_NAME/DB_USER/DB_PASSWORD/DB_PORT 保持与 3.1 节创建的值一致（koillection/koillection/koillection/5432）；DB_VERSION 必须等于实际 PostgreSQL 大版本（17），写 15 会触发 Doctrine 的版本协商问题。改完核对：

grep -E "^APP_ENV|^APP_SECRET|^JWT_PASSPHRASE|^DB_VERSION" .env

实测回显：

APP_ENV=prod
APP_SECRET=6f1c9d2a84b7e35c0a9d4f18e7b2c65a
JWT_PASSPHRASE=koillection-lab
DB_VERSION=17

4.3 安装 Composer 依赖

cd /opt/koillection
COMPOSER_MEMORY_LIMIT=-1 composer install --no-dev --no-interaction

实测回显（输出节选，实测首尾）：

  - Installing symfony/http-foundation (v8.1.9): Extracting archive
  - Installing symfony/http-kernel (v8.0.13): Extracting archive
  ...
  - Installing twig/intl-extra (v3.30.0): Extracting archive
Generating optimized autoload files
88 packages you are using are looking for funding.
Use the `composer fund` command to find out more!

Run composer recipes at any time to see the status of your Symfony recipes.

Executing script cache:clear [OK]
Executing script assets:install public [OK]

--no-dev 跳过 phpunit/profiler 等开发包；官方构建同样用 COMPOSER_MEMORY_LIMIT=-1 放开内存限制。依赖装完末尾两个 [OK] 是 Symfony 的 post-install 钩子（清缓存 + 拷贝公共资源），必须出现才算成功。

⚠️ 排障实录一：Class "Symfony\Bundle\WebProfilerBundle\WebProfilerBundle" not found。 实测在 .env 还是 APP_ENV=dev 时执行 composer install --no-dev，post-install 钩子以 dev 环境启动内核，去加载只在 require-dev 里的 WebProfilerBundle 而崩溃，composer-install.log 实录：

!!  2026-10-28T10:27:25+00:00 [critical] Uncaught Error: Class "Symfony\Bundle\WebProfilerBundle\WebProfilerBundle" not found
!!  Script @auto-scripts was called via post-install-cmd

定位：--no-dev 安装 + dev 环境 + post-install 脚本三者冲突。解决：先把 .env 的 APP_ENV 改为 prod（4.2 节），再重跑 composer install --no-dev --no-interaction，两个 [OK] 出现即修复。

4.4 生成 JWT 密钥对

REST API 的 JWT 鉴权需要一对 RSA 密钥，一条命令生成到 config/jwt/：

cd /opt/koillection
php bin/console lexik:jwt:generate-keypair --no-interaction

实测回显：


 [OK] Done!

验证密钥文件已生成：

ls config/jwt/

config.pem  private.pem  public.pem

💡 技术拓展：JWT 密钥常见的两种签名算法——HS256（对称，一个共享密钥，配置简单但签发方与校验方同钥）与 RS256（非对称，私钥签名/公钥校验，支持公钥分发）。lexik 包默认 RS256，因此生成的是 private.pem/public.pem 一对文件，JWT_PASSPHRASE 用于加密私钥落盘。

4.5 执行数据库迁移

把全部表结构写入 PostgreSQL：

cd /opt/koillection
php bin/console doctrine:migrations:migrate --no-interaction

实测回显（输出节选，实测首尾）：

[notice] Migrating up to App\Migrations\Postgresql\Version20260514195923
[notice] Migration App\Migrations\Mysql\Version20200429093452 skipped during Execution. Reason: "Mysql or Mariadb migration only. Skipped."
[notice] Migration App\Migrations\Mysql\Version20200727114843 skipped during Execution. Reason: "Mysql or Mariadb migration only. Skipped."
...
[notice] finished in 11.2ms, used 16M memory, 52 migrations executed, 0 sql queries

 [OK] Successfully migrated to version:
      App\Migrations\Postgresql\Version20260514195923

Koillection 的迁移目录按数据库分成了 Mysql/ 与 Postgresql/ 两组，各迁移类内部按当前平台自行跳过对方方言（上述大量 skipped 通知是正常现象）。验证表已建成：

PGPASSWORD=koillection psql -h 127.0.0.1 -U koillection -d koillection -Atc \
    "select count(*) from information_schema.tables where table_schema='public'"

27

27 张 koi_* 前缀表（收藏集、条目、标签、愿望单等）全部就位。

⚠️ 排障实录二：FATAL: password authentication failed for user "koillection"。 实测迁移时若数据库角色口令与 .env 的 DB_PASSWORD 不一致，报错实录：

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

定位：角色存在但口令未设置/不一致（3.1 节漏做 ALTER USER）。解决：按 3.1 节执行 ALTER USER 后重跑迁移，出现 [OK] Successfully migrated to version 即修复。

五、构建前端静态资源

Koillection 仓库不带预编译前端，public/build/ 需要现场用 Vite 构建出来——漏掉这步所有页面都会 500。

5.1 导出 JavaScript 翻译文件

前端界面文案由后端翻译文件导出生成，先执行导出：

cd /opt/koillection
php bin/console app:translations:dump

实测回显：

Dumping translations files into /opt/koillection/assets/js...
Done!

5.2 yarn install 与 yarn build

cd /opt/koillection/assets
yarn install
yarn build

yarn install 实测回显（输出节选，实测末尾）：

➤ YN0000: ┌ Link step
➤ YN0000: └ Completed in 1s 294ms
➤ YN0000: └ Completed

yarn build 实测回显（输出节选，实测首尾）：

../public/build/timezone_controller-CbV2FcKz.js              0.19 kB │ gzip:   0.17 kB
../public/build/compact-visibility_controller-B9Lr7TBC.js    0.37 kB │ gzip:   0.25 kB
...
../public/build/app-BwWvCTpp.js                            297.94 kB │ gzip:  78.02 kB
../public/build/install-BVdVbGy3.js                        451.86 kB │ gzip: 153.56 kB

✓ built in 554ms

⚠️ 网络说明：yarn 首次安装依赖需访问 npm registry，境外网络不畅时为 corepack/yarn 配代理（export https_proxy=http://192.168.1.62:7897）后重跑。实测环境构建一次约 0.6 秒（依赖缓存命中的二次构建更快）。

5.3 验证构建产物

ls /opt/koillection/public/build/entrypoints.json /opt/koillection/public/build/manifest.json

/opt/koillection/public/build/entrypoints.json
/opt/koillection/public/build/manifest.json

⚠️ 排障实录三：整站 500，日志报 Could not find the entrypoints file "/opt/koillection/public/build/entrypoints.json". Did the assets get built?。 实测跳过本章直接访问站点时，var/log/prod.log 出现该 critical 日志，任何页面都返回 500。定位：base.html.twig 引用 Encore/Reprise 的 entrypoints 清单，而源码仓库不含 public/build/。解决：执行 5.1 + 5.2 后产物生成，页面恢复 200。这是源码部署 Koillection 最常见的翻车点。

六、配置 nginx 站点

6.1 站点配置文件

新建 /etc/nginx/sites-available/koillection（实测监听 8143 端口，生产可改 80/443）：

server {
    listen 8143;
    listen [::]:8143;
    server_name _;
    root /opt/koillection/public;
    index index.php;
    access_log /var/log/nginx/koillection.access.log;
    error_log  /var/log/nginx/koillection.error.log;
    client_max_body_size 32m;
    location / {
        try_files $uri /index.php$is_args$args;
    }
    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/run/php/php8.5-fpm.sock;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        internal;
    }
    location ~ \.php$ {
        return 404;
    }
}

逐项说明：root 必须指向源码的 public/ 子目录（入口是 public/index.php，不是仓库根）；try_files $uri /index.php$is_args$args 让所有非静态请求走 Symfony 路由；PHP 只允许经 index.php 入口执行（internal + 两条 location 配合，杜绝任意 PHP 直连解析）；client_max_body_size 32m 给条目图片上传留出余量。启用站点并重载：

ln -sf /etc/nginx/sites-available/koillection /etc/nginx/sites-enabled/koillection
nginx -t
systemctl reload nginx

实测回显：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

6.2 修正属主与权限

php-fpm 以 www-data 运行，需要写应用缓存目录与上传目录：

mkdir -p /opt/koillection/public/uploads
chown -R www-data:www-data /opt/koillection/var /opt/koillection/public/uploads

验证 PHP-FPM socket 就位：

grep -E "^listen" /etc/php/8.5/fpm/pool.d/www.conf

listen = /run/php/php8.5-fpm.sock

与 nginx 配置里 fastcgi_pass unix:/run/php/php8.5-fpm.sock 一致即可。若中途曾以 root 执行过 cache:clear，务必重跑上面的 chown，否则 www-data 写缓存失败会再次 500。

6.3 首次连通性验证

curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" http://127.0.0.1:8143/

实测回显：

302 -> /first-connection

返回 302 并指向 /first-connection（首次连接引导页）说明 PHP-FPM、nginx、数据库三层全部打通——Koillection 在没有任何用户时会强制跳转到管理员初始化页。

七、首次初始化：创建管理员

7.1 /first-connection 表单

浏览器打开 http://<服务器IP>:8143/，自动进入管理员创建页，表单字段如下（实测自页面 HTML）：

字段说明本文取值
Username登录名admin
Email邮箱，全局唯一admin@example.com
Password（两次）登录口令q1w2e3r4
Timezone下拉，时区Asia/Shanghai
Date format下拉，日期格式（yyyy-mm-dd / dd-mm-yyyy / mm-dd-yyyy）yyyy-mm-dd

提交后实测跳转 302 -> /collections，进入收藏集主页，初始化即完成。数据库侧核对管理员已建且带管理员角色：

su postgres -c "psql -d koillection -Atc \"select username,email,enabled,roles from koi_user\""

admin|admin@example.com|t|["ROLE_USER","ROLE_ADMIN"]

⚠️ 排障实录四：脚本方式提交注册报 Expected argument of type "string", "null" given at property path "dateFormat"。 实测用 curl 只提交 username/email/password 四个字段时 500（var/log/prod.log 原文），原因是表单还有 timezone 与 dateFormat 两个 select 字段，缺省为 null 而实体属性声明为非空字符串。浏览器正常填写不会遇到；写自动化脚本时必须带上 user[timezone] 与 user[dateFormat] 两个字段。

八、安装后验证

8.1 登录测试

Koillection 的登录页就是站点根路径。实测登录（真实服务器上在浏览器输入 admin / q1w2e3r4 即可；下面是等价的命令行验证）：

JAR=/tmp/lj.txt; rm -f $JAR
TOK=$(curl -s -c $JAR http://127.0.0.1:8143/ | grep -oP 'csrf_token" value="\K[^"]+' | head -1)
curl -s -b $JAR -c $JAR -o /dev/null -w "LOGIN:%{http_code} -> %{redirect_url}\n" \
    -X POST http://127.0.0.1:8143/ \
    --data-urlencode "_username=admin" \
    --data-urlencode "_password=q1w2e3r4" \
    --data-urlencode "_csrf_token=$TOK"
curl -s -b $JAR http://127.0.0.1:8143/ -o /dev/null -w "HOME:%{http_code}\n"

实测回显：

LOGIN:302 -> http://127.0.0.1:8143/
HOME:200

登录 302 后带着会话 Cookie 访问主页返回 200，页面 <title>Koillection</title>，即收藏集管理主界面。

8.2 REST API 验证

curl -s -o /dev/null -w "API:%{http_code}\n" http://127.0.0.1:8143/api
curl -s -o /dev/null -w "APIDOCS:%{http_code} size:%{size_download}\n" http://127.0.0.1:8143/api/docs

实测回显：

API:200
APIDOCS:200 size:187698

/api 是 API Platform 入口，/api/docs 返回完整的 OpenAPI 描述（约 183 KB），证明 4.4 节的 JWT 密钥对已被 API 层正常加载。

8.3 进程与端口核对

ss -tlnp | grep -E "8143|5432"

实测回显（输出节选）：

LISTEN 0  200  127.0.0.1:5432   0.0.0.0:*  users:(("postgres",pid=22,fd=5))
LISTEN 0  511  0.0.0.0:8143     0.0.0.0:*  users:(("nginx",pid=42,fd=23))

PostgreSQL 只监听本机 5432（PHP 与它同机，安全），nginx 对外监听 8143。

九、升级与卸载

9.1 升级到新版本

升级 = 换代码 → 重装依赖 → 迁移 → 重建前端，四步走（以升级到未来发布的 X.Y.Z 标签为例，命令为可执行形态）：

cd /opt/koillection
git fetch --tags
git checkout X.Y.Z
COMPOSER_MEMORY_LIMIT=-1 composer install --no-dev --no-interaction
php bin/console doctrine:migrations:migrate --no-interaction
php bin/console app:translations:dump
cd assets && yarn install && yarn build && cd ..
chown -R www-data:www-data var public/uploads

每一步的预期回显与首次安装一致（composer 末尾两个 [OK]、migrate 末尾 [OK] Successfully migrated、build 末尾 ✓ built）。升级前备份：pg_dump -U koillection koillection > backup.sql 加 public/uploads/ 目录整体拷贝。

9.2 卸载

按依赖的反向顺序拆除：

rm /etc/nginx/sites-enabled/koillection /etc/nginx/sites-available/koillection
systemctl reload nginx
su postgres -c "dropdb koillection && dropuser koillection"
rm -rf /opt/koillection
apt-get purge -y php8.5* postgresql nginx

十、常见问题（FAQ）

Q1：页面全是 500，prod.log 里都是 entrypoints.json？ 前端没构建。执行第五章 5.1/5.2，确认 public/build/entrypoints.json 存在（排障实录三）。

Q2：composer install 末尾报 WebProfilerBundle not found？ .env 还是 APP_ENV=dev 却用了 --no-dev 安装。改 APP_ENV=prod 后重跑（排障实录一）。

Q3：迁移报 password authentication failed？ 数据库角色口令与 DB_PASSWORD 不一致，ALTER USER 重设后重试（排障实录二）。

Q4：上传图片失败？ public/uploads/ 不存在或属主不是 www-data。mkdir -p + chown -R www-data:www-data（6.2 节），并确认 nginx client_max_body_size 不小于上传体积。

Q5：想换 MySQL/MariaDB？ 装 php8.5-mysql，.env 里 DB_DRIVER=pdo_mysql 并改 DB_NAME/DB_USER/DB_PASSWORD/DB_VERSION，重跑迁移即可；官方标注支持 MySQL ≥ 8.0、MariaDB ≥ 10（本文实测为 PostgreSQL，切换步骤未实测，以官方 Wiki 为准）。

参考链接

  1. 官方仓库：https://github.com/koillection/koillection
  2. 官方安装 Wiki：https://github.com/koillection/koillection/wiki/Installation
  3. 官方配置 Wiki：https://github.com/koillection/koillection/wiki/Configuration
  4. Sury PHP 源：https://packages.sury.org/php/
  5. Node.js 官方二进制下载：https://nodejs.org/dist/
  6. 站内延伸：《Koillection 1.8.5 介绍与选型指南》、《Koillection 1.8.5 配置参数详解》、《Koillection 1.8.5 常用 CLI 命令与工具详解》