Pelican Panel Docker Compose 部署指南

目标：在 Ubuntu 24.04.5 上用 Docker Compose 部署 Pelican Panel v1.0.0-rc.2（官方 ghcr.io/pelican/panel 分发 + MariaDB + Redis 三件套），完成数据库迁移、管理员创建、安装收尾与登录闭环验证。本文全部命令与回显为 2026-11-02/03 实测，含 plugins 子路径挂载、目录属主权限、healthcheck 误报 unhealthy 三条排障实录。

一、环境信息

项目	值
主机 OS	Ubuntu 24.04.5 LTS（内核 x86_64）
Docker	29.9.2, build a82e528
Docker Compose	v5.6.1
面板	`ghcr.io/pelican/panel:v1.0.0-rc.2`（镜像 ID `cb717c15da9b`，磁盘占用 838MB / 内容 164MB）
面板内置	PHP 8.5.12、Caddy v2.11.4、supervisord（php-fpm + queue-worker + caddy 三进程）
数据库	`mariadb:10.11`（镜像 ID `d769e3796082`）
缓存/队列	`redis:alpine`
访问地址	`http://192.168.1.172:8132`（宿主 IP : 宿主端口 = 面板端口）
compose 项目名	`pelican-v1.0.0-rc.2-stack`（卷/网络实名规范化为 `pelican-v100-rc2-stack_*`）
自定义网络	bridge，子网 `10.89.59.0/24`
数据卷	`pelican-data`（/pelican-data）、`pelican-logs`（面板日志）、`pelican-db`（MySQL 数据）
演示账号	`root` / `q1w2e3r4`（管理员，实测创建并验证）
实测日期	2026-11-02 起栈、2026-11-03 安装收尾与复核

二、镜像选型说明

官方分发仓库为 ghcr.io/pelican/panel（GitHub Container Registry），tag 形态实查：

tag	说明
`v1.0.0-rc.2`	本次部署钉住的发布候选（2026-10-22 发布）
`latest`	跟随最新 release，会漂移，生产不建议
`main`	主干滚动构建，仅供尝鲜

要点：

镜像内置完整运行栈：PHP 8.5.12 + php-fpm、Caddy v2.11.4（Web 服务器，站点地址由 APP_URL 生成）、supervisord（拉起 php-fpm、queue-worker、caddy 三进程），入口为 /bin/ash /entrypoint.sh（docker compose ps 的 COMMAND 列实测可见）；
面板自身不跑游戏服务器——游戏实例在节点侧由 Wings（Go 编写，github.com/pelican/wings，最新 v1.0.0-rc.1）托管，本文只覆盖控制面三件套；
依赖 MariaDB/MySQL 与 Redis，官方 compose 形态用 mariadb + redis 官方镜像即可，无版本硬约束（本次实测 10.11 / alpine 通过）；
网络说明：ghcr.io 直连拉取成功，未走代理降级链。

⚠️ 面板要求 PHP 8.4+（rc.2 changelog："Require PHP 8.4 in the installer to match composer"），官方镜像已内置 8.5.12，无需自备 PHP。

三、前置条件

# Docker 与 Compose 版本确认（实测）
$ docker --version
Docker version 29.9.2, build a82e528
$ docker compose version
Docker Compose version v5.6.1

# 宿主端口占用检查：部署前 8132 空闲（实测复核通过）
$ ss -ltn | grep ':8132' || echo 'ports free'
ports free

准备部署目录（本例 /opt/data/quzuo/tmp/pelican-panel，下文以 . 指代）：

mkdir -p ./pelican-panel && cd ./pelican-panel

四、部署步骤

4.1 编写 docker-compose.yml

完整实测版本（含 healthcheck 修复，见 4.8；锚点复用官方 compose-full-stack.yml 风格）：

name: pelican-v1.0.0-rc.2-stack

x-common:
  panel:
    &panel-environment
    APP_URL: "http://192.168.1.172:8132"
    APP_DEBUG: "false"
    APP_ENV: "production"

  mail:
    &mail-environment
    MAIL_DRIVER: "log"

  database:
    &db-environment
    MYSQL_ROOT_PASSWORD: "q1w2e3r4"
    MYSQL_PASSWORD: &db-password "q1w2e3r4"
    MYSQL_DATABASE: &db-database "panel"
    MYSQL_USER: &db-username "pelican"

services:
  database:
    image: mariadb:10.11
    container_name: pelican-v1.0.0-rc.2-database
    restart: always
    command: --default-authentication-plugin=mysql_native_password
    volumes:
      - pelican-db:/var/lib/mysql
    environment:
      <<: *db-environment

  cache:
    image: redis:alpine
    container_name: pelican-v1.0.0-rc.2-cache
    restart: always

  panel:
    image: ghcr.io/pelican/panel:v1.0.0-rc.2
    container_name: pelican-v1.0.0-rc.2-panel
    restart: unless-stopped
    depends_on:
      - database
      - cache
    ports:
      - "8132:8132"
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:8132/up || exit 1; cgi-fcgi -bind -connect 127.0.0.1:9000 >/dev/null || exit 2"]
      interval: 30s
      timeout: 10s
      start_period: 120s
      retries: 3
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - pelican-data:/pelican-data
      - pelican-logs:/var/www/html/storage/logs
      - type: volume
        source: pelican-data
        target: /var/www/html/plugins
        volume:
          subpath: plugins
    environment:
      <<: [*panel-environment, *mail-environment]
      XDG_DATA_HOME: /pelican-data
      CACHE_STORE: "redis"
      SESSION_DRIVER: "redis"
      QUEUE_CONNECTION: "redis"
      REDIS_HOST: "cache"
      DB_CONNECTION: "mariadb"
      DB_HOST: "database"
      DB_PORT: "3306"
      DB_DATABASE: *db-database
      DB_USERNAME: *db-username
      DB_PASSWORD: *db-password

volumes:
  pelican-data:
  pelican-logs:
  pelican-db:

networks:
  default:
    ipam:
      config:
        - subnet: 10.89.59.0/24

逐项说明：

name: 显式项目名——compose 默认用目录名做项目名，多栈并存时 down 会误删他人栈，必须显式命名；注意 compose 会把项目名中的点号规范化掉（pelican-v1.0.0-rc.2-stack → 卷/网络前缀 pelican-v100-rc2-stack_）；
APP_URL 是最关键的变量：面板站点地址、Caddy 监听端口、资产 URL 全部由它派生（http://192.168.1.172:8132 意味着 Caddy 只监听 8132，这直接导致 4.8 的 healthcheck 排障）；
DB_* 与 MYSQL_* 锚点对应：面板用 pelican/q1w2e3r4 连接 panel 库，MariaDB 初始化时按同名创建；
CACHE_STORE/SESSION_DRIVER/QUEUE_CONNECTION 三项全指 redis（实测 p:info Drivers 段回显一致）；
XDG_DATA_HOME: /pelican-data：把面板数据（.env、caddy、database、storage、plugins）收敛到数据卷；
plugins 子路径卷挂载（subpath: plugins）：把 pelican-data 卷内的 plugins 子目录额外挂到 /var/www/html/plugins，让插件目录跨重建持久化——首次创建卷时有坑，见 4.2；
healthcheck 块是对官方镜像内置检查的修正（原版硬编码 80 端口导致永远 unhealthy，见 4.8），不要照抄官方示例省略此块；
extra_hosts: host-gateway：为后续节点侧 SFTP/回调等场景预留宿主访问通道，纯控制面部署可省略。

4.2 预建 plugins 子目录（排障实录一）

全新 pelican-data 卷里还没有 plugins 目录，直接起栈时 Docker 对 subpath 挂载报错（实测错误原文）：

Error response from daemon: cannot access path "/var/lib/docker/volumes/pelican-v100-rc2-stack_pelican-data/_data/plugins" from local (volume: pelican-v100-rc2-stack_pelican-data): no such file or directory

定位：compose 的 named volume subpath 挂载不会自动创建卷内子目录。解决：借任意一次性进程在卷内预建（实测）：

$ docker run --rm -v pelican-v100-rc2-stack_pelican-data:/data redis:alpine mkdir -p /data/plugins

再执行 4.4 起栈即通过。（entrypoint.sh 自身也会 mkdir -p /pelican-data/plugins，但 subpath 挂载发生在容器启动之前，必须先建。）

4.3 拉取镜像

$ docker pull ghcr.io/pelican/panel:v1.0.0-rc.2

拉取成功后本地确认（实测）：

$ docker images | grep pelican
ghcr.io/pelican/panel:v1.0.0-rc.2    cb717c15da9b   838MB   164MB

4.4 起栈

$ docker compose -f compose.yml up -d
 Container pelican-v1.0.0-rc.2-cache Running
 Container pelican-v1.0.0-rc.2-panel Running
 Container pelican-v1.0.0-rc.2-database Running

（上面回显为栈已在运行时的幂等输出；首次创建时对应行是 Created/Started。）

4.5 首启行为与安装向导

entrypoint.sh 首启逻辑（源码实测摘录）：无 /pelican-data/.env 时自动生成 APP_KEY 并写入 APP_INSTALLED=false，创建 database/storage/avatars/fonts/icons/plugins 等目录；APP_INSTALLED=false 时不跑迁移，Web 进入安装向导：

$ curl -s -o /dev/null -w '%{http_code} / -> %{redirect_url}\n' http://192.168.1.172:8132/
302 -> http://192.168.1.172:8132/installer
$ curl -s -o /dev/null -w '%{http_code} /installer\n' http://192.168.1.172:8132/installer
200

官方推荐在 /installer 页面完成初始化。本环境浏览器自动化通道不可用，改走 artisan CLI 等价路线（4.6）——两条路线产物相同：.env 三键 + 迁移表 + 管理员 + APP_INSTALLED=true。

⚠️ 用 curl/脚本模拟 Web 表单登录与安装不可行：登录页为 Filament/Livewire 表单，请求快照带服务端 HMAC 校验（hash_hmac('sha256', ..., app key)），客户端无法伪造签名——这是正常安全行为，不是部署故障。表单类操作请用浏览器，或按 4.6 走 CLI。

4.6 CLI 安装主线（实测）

以下命令均在 panel 服务内执行（docker compose exec panel php artisan ...，为省版面后文只写 php artisan ... 部分）：

第 1 步：环境初始化

$ php artisan p:environment:setup --url=http://192.168.1.172:8132

实测回显（节选）：

 Writing APP_URL
 Creating storage link
 ERROR  The [public/storage] link already exists.
 Caching components & icons  DONE

storage link already exists 为幂等提示，不影响流程（见 FAQ 10.9）。

第 2 步：建表与种子数据

$ php artisan migrate --seed --force

实测：全部迁移进入 batch [1] 并 Ran，随后输出 Seeding database。安装完成后复核（实测回显节选）：

$ php artisan migrate:status | tail -4
  2026_10_02_000000_remove_illegal_subusers_again .................... [1] Ran
  2026_10_03_000000_add_timezone_to_schedules ........................ [1] Ran
  2026_10_10_000000_repair_released_primary_allocations .............. [1] Ran
$ php artisan migrate:status | grep -c "Ran"
255

255 条迁移全部执行。

第 3 步：创建管理员

$ php artisan p:user:make --email=admin@example.com --username=root --password=q1w2e3r4 --admin=1

实测回显（节选）：

 UUID: a0f24380-3d33-47d3-82a2-44e264a30dd3
+----------+-------+
| Username | Admin |
+----------+-------+
| root     | Yes   |
+----------+-------+

第 4 步：标记安装完成并重建

$ sed -i 's/^APP_INSTALLED=false/APP_INSTALLED=true/' /pelican-data/.env
$ docker compose -f compose.yml up -d

APP_INSTALLED=true 后 entrypoint 每次启动会自动等待数据库并跑 php artisan migrate --force（升级后无需手工迁移）。

4.7 目录属主权限（排障实录二）

预建 plugins 子目录的一次性进程以 root 落盘，目录属主 root:root 且权限 700，面板进程用户 www-data（UID 82）读不了，起栈后面板报错（实测错误原文）：

RecursiveDirectoryIterator::__construct(/var/www/html/plugins): Permission denied

定位：ls -la /pelican-data 见 plugins 目录 drwx------ root root。解决（实测）：

$ docker compose exec -u root panel chown -R 82:82 /pelican-data/plugins

修复后 ls -la /pelican-data 复核（实测）：

drwxrwx---    2 root     www-data      4096 Oct 22 16:30 plugins

面板恢复 200 响应。若跳过 4.2 手工预建、由 entrypoint 自建目录，则不会踩到此坑。

4.8 healthcheck 误报 unhealthy（排障实录三）

现象：三件套全部正常服务（页面可开、接口 200），但 docker compose ps 里 panel 长期显示 (unhealthy)，docker inspect 健康检查 FailingStreak 一路涨到 800。

定位：镜像内置 /healthcheck.sh（实测原文）：

#!/bin/ash -e

if [ "${SKIP_CADDY:-false}" != "true" ]; then
    curl -sf http://localhost/up || exit 1
fi

cgi-fcgi -bind -connect 127.0.0.1:9000 || exit 2

exit 0

curl http://localhost/up 打的是 80 端口；而 Caddy 的站点地址由 {$CADDY_APP_URL}（= APP_URL 的 http://192.168.1.172:8132）生成，只监听 8132。于是健康检查永远 connection refused（exit 1），服务本身却完全健康——容器内 curl -sf http://localhost:8132/up 实测 200，php-fpm 9000 正常应答。

解决：在 compose 的 panel 服务上覆盖 healthcheck 指向真实端口（即 4.1 中给出的块），重建 panel：

$ docker compose -f compose.yml up -d
$ docker inspect --format '{{.State.Status}} | {{.State.Health.Status}} | FailingStreak={{.State.Health.FailingStreak}}' pelican-v1.0.0-rc.2-panel
running | healthy | FailingStreak=0

💡 说明：若你的部署把 APP_URL 设为 :80（如 BEHIND_PROXY=true 场景，entrypoint 会把 Caddy 切到内部 80 监听），官方内置 healthcheck 就无需覆盖。是否要改，取决于 APP_URL 的端口。

4.9 安装收尾验证（实测）

$ curl -s -o /dev/null -w '%{http_code} / -> %{redirect_url}\n' http://192.168.1.172:8132/
302 / -> http://192.168.1.172:8132/login
$ curl -s -o /dev/null -w '%{http_code} /installer\n' http://192.168.1.172:8132/installer
404
$ curl -s -o /dev/null -w '%{http_code} /login\n' http://192.168.1.172:8132/login
200

三条含义：根路径 302 跳 /login（安装前是跳 /installer）；/installer 已关闭（404）；登录页 200。口令侧再用 artisan 复核（实测）：

$ php artisan tinker --execute "var_dump(Hash::check('q1w2e3r4', \App\Models\User::where('username','root')->first()->password));"
bool(true)

浏览器访问 http://192.168.1.172:8132/login，用演示账号 root / q1w2e3r4 登录进入 Filament 后台即完成闭环。

五、数据持久化说明

卷	挂载点	内容	备注
`pelican-data`	`/pelican-data`	`.env`、`caddy/`、`database/`、`storage/`（avatars/fonts/icons）、`composer/`、`plugins/`	备份核心（APP_KEY 在 .env 里，丢了要重发）
`pelican-data`（subpath plugins）	`/var/www/html/plugins`	插件运行目录	与上同卷，跨重建保留
`pelican-logs`	`/var/www/html/storage/logs`	Laravel 日志（logs driver=daily 实测）
`pelican-db`	`/var/lib/mysql`	MariaDB 数据	业务数据全在 `panel` 库

/pelican-data 实测清单（面板运行态）：

-rw-r--r--    1 www-data www-data      115 Nov  3 01:54 .env
drwx------    3 www-data www-data     4096 Nov  2 19:08 caddy
drwxr-xr-x    2 www-data www-data     4096 Nov  3 01:59 composer
drwxr-xr-x    2 www-data www-data     4096 Nov  2 19:08 database
drwxrwx---    2 root     www-data     4096 Oct 22 16:30 plugins
drwxrwx---    5 www-data www-data     4096 Nov  2 19:08 storage

六、环境变量表

compose 侧实际使用的变量（全部实测生效）：

变量	实测值	说明
`APP_URL`	`http://192.168.1.172:8132`	面板地址；派生 Caddy 站点与资产 URL
`APP_ENV` / `APP_DEBUG`	`production` / `false`	Laravel 运行环境
`APP_KEY`	首启自动生成写入 `.env`	加密密钥，不要随重建丢失
`APP_INSTALLED`	`true`（安装收尾置位）	false 时进 `/installer`；true 时启动自动迁移
`DB_CONNECTION`/`DB_HOST`/`DB_PORT`	`mariadb`/`database`/`3306`	面板数据库连接
`DB_DATABASE`/`DB_USERNAME`/`DB_PASSWORD`	`panel`/`pelican`/`q1w2e3r4`	与 `MYSQL_*` 初始化变量对应
`CACHE_STORE`/`SESSION_DRIVER`/`QUEUE_CONNECTION`	均 `redis`	三驱动全走 Redis
`REDIS_HOST`	`cache`	Redis 地址
`MAIL_DRIVER`	`log`	演示环境不发真邮件
`XDG_DATA_HOME`	`/pelican-data`	数据目录收敛到卷

entrypoint 额外识别的开关（源码实测摘录，默认值见括号）：

变量	作用
`SKIP_MIGRATIONS`（false）	`true` 时启动不跑 migrate——多副本共库场景只留一个副本迁移
`BEHIND_PROXY`（false）	`true` 时 Caddy 改监听内部 `:80`、关闭 auto_https、`ASSET_URL=APP_URL`
`LE_EMAIL`（空）	`APP_URL` 为 https 且未设 BEHIND_PROXY 时必填，否则 entrypoint 直接退出（见 FAQ 10.8）
`TRUSTED_PROXIES`（空）	逗号分隔 CIDR/IP，注入 Caddy `trusted_proxies static` 并开启 strict
`SKIP_CADDY`（false）	`true` 时只起 php-fpm，Web 服务器自备

七、配置文件挂载

.env 落点：/pelican-data/.env（webroot /var/www/html/.env 是指向它的符号链接）。安装完成后实测内容仅三行：

APP_KEY=base64:Y/r7AYk2MUDviAR0peoZxNg0sOWCvhMCgM2K5LB0VeA=
APP_INSTALLED=true
APP_URL="http://192.168.1.172:8132"

其余配置全部走 compose environment: 注入——这是官方 Compose 形态与裸机安装最大的配置差异（裸机是完整 Laravel .env）。.env 键位逐项详解见本专栏《Pelican Panel v1.0.0-rc.2 配置参数详解》。

镜像内出厂模板 /var/www/html/.env.example 实测仅 6 行：APP_ENV、APP_DEBUG、APP_KEY、APP_URL、APP_INSTALLED、APP_LOCALE。
配置缓存被官方禁用：php artisan config:cache 实测回显 WARN Configuration caching has been disabled. Reason: This application uses dynamic plugins.——动态插件体系决定的，不是故障。

八、等价 docker run

与 4.1 compose 中 panel 服务等价的单命令路线（实测验证过：独立进程 pelican-100rc2-runtest，宿主端口 18132，验证后已删除）。复用同一批 named volume 与 compose 网络，用 SKIP_MIGRATIONS=true 避免与主实例重复迁移：

$ docker run --rm -d --name pelican-100rc2-runtest \
  --network pelican-v100-rc2-stack_default \
  -p 18132:8132 \
  -e APP_URL="http://192.168.1.172:8132" -e APP_DEBUG=false -e APP_ENV=production \
  -e MAIL_DRIVER=log -e XDG_DATA_HOME=/pelican-data \
  -e CACHE_STORE=redis -e SESSION_DRIVER=redis -e QUEUE_CONNECTION=redis -e REDIS_HOST=cache \
  -e DB_CONNECTION=mariadb -e DB_HOST=database -e DB_PORT=3306 -e DB_DATABASE=panel \
  -e DB_USERNAME=pelican -e DB_PASSWORD=q1w2e3r4 \
  -e SKIP_MIGRATIONS=true \
  -v pelican-v100-rc2-stack_pelican-data:/pelican-data \
  -v pelican-v100-rc2-stack_pelican-logs:/var/www/html/storage/logs \
  ghcr.io/pelican/panel:v1.0.0-rc.2
454730aff4be31565074c11a6551ed2310292cf410e73c70a81b8e9f81ac6261

启动日志实测（头部节选，可见 entrypoint 的 .env 加载与 SKIP_MIGRATIONS 分支）：

.env vars exist.
checking for APP_KEY
loading APP_KEY from .env
checking for APP_INSTALLED
loading APP_INSTALLED from .env
checking for DB_CONNECTION
DB_CONNECTION already set in environment, skipping
...
Checking database status.
database (10.89.59.3:3306) open
Skipping migrations (SKIP_MIGRATIONS=true)
Optimizing Filament

Web 验证（实测）：

$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:18132/login
200
$ docker rm -f pelican-100rc2-runtest

⚠️ 单命令路线无法复现 compose 的 subpath: plugins 挂载（docker run 不支持卷子路径）；如需插件持久化请回到 Compose 形态。

九、常用运维命令

# 栈状态（实测回显）
$ docker compose -f compose.yml ps
NAME                           IMAGE                               COMMAND                  SERVICE    CREATED          STATUS                    PORTS
pelican-v1.0.0-rc.2-cache      redis:alpine                        "docker-entrypoint.s…"   cache      7 hours ago      Up 7 hours                6379/tcp
pelican-v1.0.0-rc.2-database   mariadb:10.11                       "docker-entrypoint.s…"   database   7 hours ago      Up 7 hours                3306/tcp
pelican-v1.0.0-rc.2-panel      ghcr.io/pelican/panel:v1.0.0-rc.2   "/bin/ash /entrypoin…"   panel      19 minutes ago   Up 19 minutes (healthy)   80/tcp, 443/tcp, 9000/tcp, 0.0.0.0:8132->8132/tcp, [::]:8132->8132/tcp

# 日志跟踪
docker compose -f compose.yml logs -f panel

# 进面板跑 artisan（CLI 全解见本专栏命令篇）
docker compose exec panel php artisan p:info

# 停栈（保留数据）/ 彻底拆栈（含卷，慎用）
docker compose -f compose.yml down
docker compose -f compose.yml down -v

# 升级：改 compose 中 tag → 拉新镜像 → 重建（APP_INSTALLED=true 时启动自动迁移）
docker pull ghcr.io/pelican/panel:<新版本>
docker compose -f compose.yml up -d

# 备份：停栈后打包数据卷（.env 含 APP_KEY，务必备出）
docker compose -f compose.yml stop
docker run --rm -v pelican-v100-rc2-stack_pelican-data:/data -v "$(pwd)":/backup redis:alpine \
  tar czf /backup/pelican-data-$(date +%F).tar.gz -C /data .
docker compose -f compose.yml start

十、常见问题

10.1 起栈报 `cannot access path .../_data/plugins: no such file or directory`

官方 compose 的 plugins subpath 挂载在全新 named volume 上必报此错。解决：见 4.2，用一次性进程 mkdir -p /data/plugins 预建卷内子目录。

10.2 面板报 `RecursiveDirectoryIterator::__construct(/var/www/html/plugins): Permission denied`

预建目录属主 root:root 700，面板用户 www-data（UID 82）无权读。解决：docker compose exec -u root panel chown -R 82:82 /pelican-data/plugins（实测有效，见 4.7）。

10.3 服务正常但一直 `(unhealthy)`

镜像内置 /healthcheck.sh 硬编码探测 80 端口，而 Caddy 按 APP_URL 只监听你指定的端口（本例 8132）。解决：compose 覆盖 healthcheck 指向 http://localhost:8132/up（见 4.1/4.8，实测复核 running | healthy | FailingStreak=0）。

10.4 `php artisan migrate` 不带 `--force` 被取消

生产环境（APP_ENV=production）下不带 --force 的迁移会交互确认，非交互通道实测回显：

   WARN  Command cancelled.

解决：安装与升级一律 php artisan migrate --force（entrypoint 自动迁移时同样带 --force）。

10.5 `/installer` 返回 404

APP_INSTALLED=true 后安装向导自动关闭（实测 404），属预期。需要重装请拆卷重来，或手工把 .env 中 APP_INSTALLED 改回 false 并清库。

10.6 curl 模拟登录/安装表单失败

Livewire 表单快照带服务端 HMAC 签名，脚本伪造不了（见 4.5 的 ⚠️）。用浏览器操作，或走 4.6 的 artisan CLI 路线。

10.7 `config:cache` 出现 WARN 禁用提示

动态插件体系与配置缓存互斥，官方显式禁用（实测回显见七）。不要试图绕过；性能优化走 cache:clear 与 opcache 路线。

10.8 `APP_URL` 设成 https 后面板起不来

entrypoint 实测逻辑：https 且未设 BEHIND_PROXY=true 时必须提供 LE_EMAIL，否则打印 when app url is https a lets encrypt email must be set when not behind a proxy 并退出 1。二选一：给 LE_EMAIL 走内置 Caddy 自动证书，或 BEHIND_PROXY=true 交给外部反代终结 TLS。

10.9 `p:environment:setup` 报 `The [public/storage] link already exists`

官方镜像已预建符号链接，setup 重复创建失败属幂等噪音，不影响安装（实测后续步骤全部正常）。

十一、参考链接

官方仓库：https://github.com/pelican/panel
官方 Compose 示例（compose-full-stack.yml）：仓库根目录
节点守护进程 Wings：https://github.com/pelican/wings
官网：https://pelican.dev
站内相关：《Pelican Panel 介绍与选型指南》、《Pelican Panel v1.0.0-rc.2 配置参数详解》、《Pelican Panel v1.0.0-rc.2 常用 CLI 命令与工具详解》、《Crafty Controller Docker Compose 部署指南》（单机一体化路线对照）

（全部命令与回显实测日期 2026-11-02/03。）

Pelican Panel Docker Compose 部署指南

Pelican Panel Docker Compose 部署指南

一、环境信息

二、镜像选型说明

三、前置条件

四、部署步骤

4.1 编写 docker-compose.yml

4.2 预建 plugins 子目录（排障实录一）

4.3 拉取镜像

4.4 起栈

4.5 首启行为与安装向导

4.6 CLI 安装主线（实测）

4.7 目录属主权限（排障实录二）

4.8 healthcheck 误报 unhealthy（排障实录三）

4.9 安装收尾验证（实测）

五、数据持久化说明

六、环境变量表

七、配置文件挂载

八、等价 docker run

九、常用运维命令

十、常见问题

10.1 起栈报 cannot access path .../_data/plugins: no such file or directory

10.2 面板报 RecursiveDirectoryIterator::__construct(/var/www/html/plugins): Permission denied

10.3 服务正常但一直 (unhealthy)

10.4 php artisan migrate 不带 --force 被取消

10.5 /installer 返回 404

10.6 curl 模拟登录/安装表单失败

10.7 config:cache 出现 WARN 禁用提示

10.8 APP_URL 设成 https 后面板起不来

10.9 p:environment:setup 报 The [public/storage] link already exists

十一、参考链接

10.1 起栈报 `cannot access path .../_data/plugins: no such file or directory`

10.2 面板报 `RecursiveDirectoryIterator::__construct(/var/www/html/plugins): Permission denied`

10.3 服务正常但一直 `(unhealthy)`

10.4 `php artisan migrate` 不带 `--force` 被取消

10.5 `/installer` 返回 404

10.7 `config:cache` 出现 WARN 禁用提示

10.8 `APP_URL` 设成 https 后面板起不来

10.9 `p:environment:setup` 报 `The [public/storage] link already exists`