Docker Compose

使用 Herta-Network/ppanel-edge 仓库检出目录。容器文件统一位于 docker/：Dockerfile、compose.yml、compose.valkey.yml、compose.build.yml 与 .env.example。镜像为 ghcr.io/herta-network/ppanel-edge，默认运行时为 Bun。构建阶段冻结依赖并使用 Bun 1.x；运行容器为非 root、只读文件系统，内置健康检查。

配置与启动复制标题链接

git clone https://github.com/Herta-Network/ppanel-edge.git
cd ppanel-edge/docker
cp .env.example .env
# 启动前替换所有占位值。
docker compose config --quiet
docker compose up -d

填写不同的数据库密码与匹配的 DATABASE_URL、MIGRATION_DATABASE_URL、新 MASTER_KEYS、独立随机 INSTALL_TOKEN，以及真实 SITE_HOSTS。在仓库根目录用 bun run --cwd apps/api ops:keygen --output /secure/master-key 生成主密钥，再复制受保护文件的值。限制 .env 与 Docker daemon 访问权限。修改环境密码不会自动轮换已有数据库密码。

alpha 阶段示例选择 :alpha，稳定上线后才提供默认 :latest。单次 migrate 服务安装空库和种子或执行 expand 升级，成功后 API 才启动；迁移账号与 API 的受限 app 账号分离。数据库与缓存无公开端口；API 映射主机回环 3000（HTTP_PORT 可改映射）。添加 HTTPS 反向代理，再凭 INSTALL_TOKEN 完成 /admin/install。向导前 /readyz 返回 not_installed，完成后检查健康与就绪成功。

选择 Redis、Valkey 或 Node复制标题链接

compose.yml 使用官方 Redis 8.10.2。独立 compose.valkey.yml 使用官方 Valkey 9.1.2：

docker compose -f compose.valkey.yml up -d

两套都保持服务名 redis、REDIS_URL=redis://redis:6379、私有网络与禁用缓存持久化。PostgreSQL 使用命名卷。升级与维护始终使用选择的同一 Compose 文件。

Bun 稳定标签为 X.Y.Z、X.Y、X、latest；预发布为 X.Y.Z-alpha.N、alpha。Node 对应标签追加 -node，包括 alpha-node 与 latest-node。用 PPANEL_IMAGE 固定标签或摘要。Node 可设为 ghcr.io/herta-network/ppanel-edge:alpha-node 或固定 -node 版本，已发布镜像自带运行时选择。

本地构建复制标题链接

设置 RUNTIME_TARGET=bun 或 node 与本地 PPANEL_IMAGE 标签，在 docker/ 中执行：

docker compose -f compose.yml -f compose.build.yml build api
docker compose -f compose.yml -f compose.build.yml up -d --no-build

覆盖文件同样适用于 compose.valkey.yml。仓库根目录可用 docker build -f docker/Dockerfile --target bun .，bun 是最后默认目标；ARG BUN_VERSION 默认 1。每次只构建一个镜像，保留足够内存。

升级与回滚复制标题链接

先备份数据库、对象与密钥，审查发布说明与 schema 兼容性，修改 PPANEL_IMAGE 后执行 docker compose pull && docker compose up -d。涉及迁移时先停 API 流量，确认 docker compose run --rm migrate 成功，再重建 migrate/api 后恢复流量。禁止日常升级使用 down --volumes。

应用回滚时恢复上个 PPANEL_IMAGE，拉取并重建服务，但必须满足 schema 兼容窗口；不要自动回滚数据库迁移。保留旧版本标签与摘要，参见升级指南。对象桶、邮件与支付提供商在 Compose 外通过应用配置。