Coolify 4.4.6 常用 CLI 命令与工具详解

目标：讲清 Coolify 4.4.6 的三类自动化工具——编排运维命令（docker compose 全生命周期）、平台内置命令行（php artisan 运维命令族）、REST API（curl + Token 实测），全部命令与回显均在运行中的 4.4.6 实例逐条实测采集（查询日期 2026-10-21）。

一、环境信息

项目	值
平台版本	4.4.6（`GET /api/v1/version` 实测返回 `4.4.6`）
应用框架	Laravel 12.69.3 / PHP 8.4.23（`php artisan about` 实测）
部署形态	按部署篇方案 A 落地的三服务编排（coolify / postgres / redis，项目名 `source`）
配置目录	/data/coolify/source
对外端口	8000（Web 控制台与 REST API 同端口）
实测账号	root / q1w2e3r4
API 实测 Token	5\|6Uss1u13V8FpMr753gi2geWmUC86dQx5XtcDJDQ697e2a5b2（只读）、6\|UMqra32yUmpdpcy6nWpliwVo5b7DBerZYGZhOBVm5cf53c13（读写）、7\|PDLZtVleG2TnP4cKyW9F9R9ndgiFOIFdjRZe0LSu4b2e2cc4（读写+部署）

💡 说明：上表三个 Token 为本文实测专用实例的临时凭据（实例为一次性测试环境），读者操作时用自己控制台生成的 Token 替换即可，格式为「ID|密钥串」。

二、工具概览

Coolify 不提供独立的 CLI 程序（官方 README「Integrate with your workflow」列出的自动化入口是 dashboard、API、CLI、MCP 四类，其中 CLI 指平台内置命令行而非独立发布物）。实际运维中可用的三类工具：

工具	调用形态	适用场景	本文章节
编排运维命令	`docker compose ... <子命令>`（在 /data/coolify/source 下）	平台自身的启停、日志、状态、升级	四
平台内置命令行	`docker compose ... exec coolify php artisan <命令>`	管理员重置、任务诊断、清理、计划任务查看	五
REST API	`curl -H "Authorization: Bearer <Token>" http://localhost:8000/api/v1/...`	资源管理与部署触发的程序化集成（自动化主体）	六

选型解读：日常巡检与故障处置用编排命令；忘密码、队列卡死等平台级处置用内置命令行；把 Coolify 接入 CI/CD 或自研工具用 REST API——三者共用同一部署形态，无额外安装动作。

三、前置条件

已按《Coolify 4.4.6 Docker Compose 部署指南》完成部署，三服务 Up (healthy)。
命令均在部署机 /data/coolify/source 目录下执行；为省略行文，后文示例统一使用变量 COMPOSE，展开即可执行：

cd /data/coolify/source
COMPOSE='docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml'

REST API 需要先在控制台生成 Token：登录 Web 控制台（http://<服务器IP>:8000，root / q1w2e3r4）→ 左侧 Settings → API → Create new token，填名称并勾选权限（read 只读 / write 读写 / deploy 触发部署），生成后明文仅显示一次，立即保存。权限与可调用端点的对应关系见 6.6 节实测。

四、编排运维命令详解

4.1 状态总览：`docker compose ls`

查看本机全部编排项目与运行状态：

docker compose ls

NAME                STATUS              CONFIG FILES
source              running(3)          /data/coolify/source/docker-compose.yml,/data/coolify/source/docker-compose.prod.yml

💡 说明：项目名 source 由目录名推导（官方文件未显式指定），running(3) 表示三个服务全部在运行。

4.2 服务明细：`docker compose ps`

$COMPOSE ps

NAME            IMAGE                                COMMAND                  SERVICE    CREATED          STATUS                   PORTS
coolify         docker.io/coollabsio/coolify:4.4.6   "docker-php-serversi…"   coolify    9 minutes ago    Up 9 minutes (healthy)   8000/tcp, 8443/tcp, 0.0.0.0:6001-6002->6001-6002/tcp, [::]:6001-6002/tcp, 9000/tcp, 0.0.0.0:8000->8080/tcp, [::]:8000->8080/tcp
coolify-db      postgres:15-alpine                   "docker-entrypoint.s…"   postgres   10 minutes ago   Up 9 minutes (healthy)   5432/tcp
coolify-redis   redis:7-alpine                       "docker-entrypoint.s…"   redis      10 minutes ago   Up 9 minutes (healthy)   6379/tcp

三服务均应 Up (healthy)；STATUS 出现 unhealthy 或 restarting 即异常，转 4.5 查日志。

4.3 配置核验：`config --services` 与 `config --images`

不启动、只解析编排配置，用于核对生效的版本组合（改 .env 后先跑这两条再重建）：

$COMPOSE config --services
$COMPOSE config --images

postgres
redis
coolify

docker.io/coollabsio/coolify:4.4.6
postgres:15-alpine
redis:7-alpine

4.4 日志查看：`logs --tail`

$COMPOSE logs --tail 3 coolify

coolify  |   2026-10-21 15:11:01 App\Jobs\ServerManagerJob ................. 16.31ms DONE
coolify  |   2026-10-21 15:11:01 App\Jobs\ReconcileGithubRunnersJob ............. RUNNING
coolify  |   2026-10-21 15:11:01 App\Jobs\ReconcileGithubRunnersJob ........ 43.28ms DONE

💡 说明：主服务日志以 Laravel 任务调度为主线条目，RUNNING/DONE 成对出现属正常；追踪实时输出加 -f，查另两服务把服务名换成 postgres/redis。

4.5 健康复核：`docker inspect`

docker inspect coolify --format '{{.State.Health.Status}}'

healthy

应用层探针复核（免认证公开端点）：

curl -s http://localhost:8000/api/health

OK

4.6 生命周期：`restart` / `down` / `up --wait`

改完 .env（或升级）后的标准三连：

$COMPOSE restart                                   # 仅重启服务进程
$COMPOSE down --remove-orphans                     # 停止并移除（保留数据卷）
$COMPOSE up -d --remove-orphans --wait --wait-timeout 60   # 后台启动并等待健康检查通过

--wait 依赖官方健康检查（主服务需同时通过 Web /api/health 与实时通信 /up 两个探针），命令返回即代表三服务全部就绪；down 保留 coolify-db/coolify-redis 数据卷，数据不丢。

五、平台内置命令行详解（php artisan）

5.1 调用方式与命令清单

所有内置命令经编排服务执行，形态固定为 $COMPOSE exec coolify php artisan <命令>。先看命令清单（实测节选，与运维相关的重点行保留）：

$COMPOSE exec coolify php artisan list

  about                                 Display basic information about your application
  admin:delete-user                     Delete a user with comprehensive resource cleanup and phase-by-phase confirmation (works on cloud and self-hosted)
  app:init                              Cleanup instance related stuffs
 cleanup
  cleanup:database                      Cleanup database
  cleanup:deployment-queue              Cleanup application deployment queue.
  cleanup:redis                         Cleanup Redis (Horizon jobs, metrics, overlapping queues, cache locks, and related data)
  cleanup:stucked-resources             Cleanup Stucked Resources
  cleanup:unreachable-servers           Cleanup Unreachable Servers (7 days)
  root
  root:change-email                     Change Root Email
  root:reset-password                   Reset Root Password
  scheduled
  scheduled:diagnostics                 Inspect scheduled job state, due schedules, and open deliveries without changing anything
  scheduled:dispatch                    Dispatch the due scheduled backups, tasks, volume backups, and Docker cleanups

5.2 管理员维护：`root:reset-password` / `root:change-email`

管理员密码遗忘时的重置命令（交互式，会逐项询问用户名与新密码）：

$COMPOSE exec coolify php artisan root:reset-password --help

Description:
  Reset Root Password

Usage:
  root:reset-password

Options:
  -h, --help            Display help for the given command. When no command is given display help for the list command
      --silent          Do not output any message
  -q, --quiet           Only errors are displayed. All other output is suppressed
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
      --env[=ENV]       The environment the command should run under
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

💡 说明：--help 回显显示该命令无可选参数、纯交互式执行；直接去掉 --help 运行后按提示输入管理员用户名（root）与新密码即可。邮箱变更用同族 root:change-email。

5.3 平台信息总览：`about`

$COMPOSE exec coolify php artisan about

  Application Name ................................................... Coolify
  Laravel Version .................................................... 12.69.3
  PHP Version ......................................................... 8.4.23
  Environment ..................................................... production
  Debug Mode ............................................................. OFF

  Drivers ....................................................................
  Broadcasting ........................................................ reverb
  Cache ................................................................ redis
  Database ............................................................. pgsql
  Queue ................................................................ redis
  Session ........................................................... database

  Sentry .....................................................................
  Release .............................................................. 4.4.6

输出分段展示运行环境、驱动与版本，是巡检时确认「改的配置是否生效」的最快手段（配置详解篇有逐段解读）。

5.4 计划任务诊断：`schedule:list` / `scheduled:diagnostics`

查看平台全部计划任务及下次执行时间（实测全量回显）：

$COMPOSE exec coolify php artisan schedule:list

  0   *    * * *  cleanup:ssh-mux .............. Next Due: 48 minutes from now
  0   0    * * *  php artisan cleanup:redis --clear-locks  Next Due: 8 hours from now
  0   4    * * *  cleanup:scheduled-job-occurrences  Next Due: 12 hours from now
  17  3    * * *  php artisan cleanup:stucked-resources  Next Due: 12 hours from now
  0   *    * * *  php artisan sanctum:prune-expired --hours=1  Next Due: 48 minutes from now
  0   *    * * *  php artisan cleanup:database-import-uploads  Next Due: 48 minutes from now
  0   *    * * *  php artisan dns:release-orphaned-records  Next Due: 48 minutes from now
  0   *    * * *  App\Jobs\ApiTokenExpirationWarningJob  Next Due: 48 minutes from now
  0   *    * * *  App\Jobs\CheckMissingDatabaseBackupsJob  Next Due: 48 minutes from now
  0   *    * * *  App\Jobs\CheckMissingVolumeBackupsJob  Next Due: 48 minutes from now
  0   *    * * *  App\Jobs\RevalidateUnusableS3StoragesJob  Next Due: 48 minutes from now
  *   *    * * *  App\Jobs\ReconcileGithubRunnersJob  Next Due: 46 seconds from now
  */5 *    * * *  php artisan horizon:snapshot .. Next Due: 3 minutes from now
  0   0    * * *  php artisan cleanup:unreachable-servers  Next Due: 8 hours from now
  0   *    * * *  App\Jobs\PullTemplatesFromCDN  Next Due: 48 minutes from now
  0   *    * * *  App\Jobs\PullChangelog ....... Next Due: 48 minutes from now
  */2 *    * * *  App\Jobs\CleanupInstanceStuffsJob  Next Due: 46 seconds from now
  0   *    * * *  App\Jobs\CheckForUpdatesJob .. Next Due: 48 minutes from now
  0   0    * * *  App\Jobs\UpdateCoolifyJob ....... Next Due: 8 hours from now
  *   *    * * *  App\Jobs\ServerManagerJob .... Next Due: 46 seconds from now
  0   *    * * *  App\Jobs\CheckHelperImageJob . Next Due: 48 minutes from now
  *   *    * * *  php artisan scheduled:dispatch  Next Due: 46 seconds from now
  0   1,13 * * *  App\Jobs\RegenerateSslCertJob ... Next Due: 9 hours from now
  0   0    * * *  php artisan cleanup:database --yes  Next Due: 8 hours from now

只读诊断调度器心跳与到期任务（不改任何状态，排障首选）：

$COMPOSE exec coolify php artisan scheduled:diagnostics

Scheduler heartbeat: 2026-10-21T15:28:00+00:00 (40 seconds ago)

=== Docker Cleanup Jobs ===
+----+-----------+-----+-----------+------------------+--------------------+---------+----------------+
| ID | Server    | TZ  | Frequency | Schedule Key     | Last Scheduled For | Due Now | Last Execution |
+----+-----------+-----+-----------+------------------+--------------------+---------+----------------+
| 0  | localhost | UTC | 0 0 * * * | docker-cleanup:0 | never              | no      | never          |
+----+-----------+-----+-----------+------------------+--------------------+---------+----------------+

💡 说明：心跳时间距当前 1 分钟内即调度器健康；UpdateCoolifyJob（每日 0 点）即自动升级检查任务，关闭自动升级见配置详解篇 AUTOUPDATE。

5.5 队列与清理命令族

队列工作器状态（实测）：

$COMPOSE exec coolify php artisan horizon:status


   INFO  Horizon is running.

清理族命令用于部署队列堆积、资源残留等场景（均为主动清理动作，执行前确认影响面）：

命令	用途	使用时机
cleanup:stucked-resources	清理卡死的资源记录	删除应用/服务后列表仍残留
cleanup:deployment-queue	清理部署队列	队列积压大量失败任务
cleanup:redis --clear-locks	清 Redis 锁与队列残留	疑似锁未释放导致任务不动
cleanup:database	清理数据库过期数据	平台自带每日 0 点自动执行
cleanup:unreachable-servers	清理失联服务器记录	平台每日自动执行（7 天）
app:init	清理实例相关杂物	官方「初始化/复位」用途

命令本身均为零参数直接执行（--help 实测确认，如 cleanup:stucked-resources 的 Usage 仅命令名本体）；执行类命令建议在低峰期运行。

六、REST API 详解（curl 实测）

6.1 端点与认证总览

项	值（实测）
Base URL	http://<服务器IP>:8000/api/v1（与控制台同端口）
认证方式	`Authorization: Bearer <Token>` 请求头
Token 权限	`read` / `write` / `deploy` 三类，按 Token 独立授予
响应格式	JSON
限流	默认 200 次/分钟（配置详解篇 `API_RATE_LIMIT`）
实例开关	控制台 Settings → API 的启用开关，未开启时返回「API is disabled.」（见 6.6）

6.2 版本探测：GET /api/v1/version

最快的连通性与认证双验证：

TOKEN='5|6Uss1u13V8FpMr753gi2geWmUC86dQx5XtcDJDQ697e2a5b2'
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/v1/version

4.4.6

返回纯文本版本号，无需解析 JSON。

6.3 资源域列举（GET 实测）

以下为实例上逐条实测的只读端点（团队与项目已有数据，其余为空数组）：

curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/v1/teams

[{"id":1,"name":"root's Team","description":null,"is_build_server_fallback_enabled":true,"is_mcp_server_enabled":true,"personal_team":true,"show_boarding":true,"created_at":"2026-10-21T08:11:22.000000Z","updated_at":"2026-10-21T08:11:22.000000Z"}]

curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/v1/teams/1

{"id":1,"name":"root's Team","description":null,"is_build_server_fallback_enabled":true,"is_mcp_server_enabled":true,"personal_team":true,"show_boarding":true,"created_at":"2026-10-21T08:11:22.000000Z","updated_at":"2026-10-21T08:11:22.000000Z"}

curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/v1/projects

[{"id":1,"uuid":"vftort3ukmoyquwcg9viyjtm","description":"S7 文档实测项目","name":"demo-project"}]

💡 说明：description 与 name 中的中文以 \uXXXX 转义返回，属标准 JSON 序列化行为，客户端解析后即正常中文。其余列举端点同构，实测返回：/servers、/applications、/databases、/services、/deployments 均为 []（新实例无资源）。单资源查询在列表路径后追加 uuid，如 /projects/<uuid>，实测返回含 environments（默认 production 环境）的完整对象。

6.4 写操作：项目增删（POST / DELETE 实测）

创建项目（写 Token）：

WTOKEN='6|UMqra32yUmpdpcy6nWpliwVo5b7DBerZYGZhOBVm5cf53c13'
curl -s -X POST -H "Authorization: Bearer $WTOKEN" -H "Content-Type: application/json" \
  -d '{"name":"demo-api","description":"S7 D1 API 实测项目"}' \
  http://localhost:8000/api/v1/projects

{"uuid":"2wquybhdhzutysgzjhtthagp"}

返回新建资源的 uuid。删除项目：

curl -s -X DELETE -H "Authorization: Bearer $WTOKEN" \
  http://localhost:8000/api/v1/projects/2wquybhdhzutysgzjhtthagp

{"message":"Project deleted."}

删除后复核列表回到删除前状态（实测 [{"id":1,"uuid":"vftort3ukmoyquwcg9viyjtm",...}]），再对该 uuid 操作返回：

curl -s -X PATCH -H "Authorization: Bearer $WTOKEN" -H "Content-Type: application/json" \
  -d '{"name":"renamed"}' \
  http://localhost:8000/api/v1/projects/2wquybhdhzutysgzjhtthagp

{"message":"Project not found."}

6.5 部署触发：POST /api/v1/deploy

触发部署需 Token 含 deploy 权限。参数校验实测——缺参数（http=400）：

FTOKEN='7|PDLZtVleG2TnP4cKyW9F9R9ndgiFOIFdjRZe0LSu4b2e2cc4'
curl -s -X POST -H "Authorization: Bearer $FTOKEN" -o /dev/null -w 'http=%{http_code} ' \
  http://localhost:8000/api/v1/deploy
curl -s -X POST -H "Authorization: Bearer $FTOKEN" http://localhost:8000/api/v1/deploy

http=400 {"message":"You must provide uuid or tag."}

uuid 不存在（返回 JSON，HTTP 200）：

curl -s -X POST -H "Authorization: Bearer $FTOKEN" -H "Content-Type: application/json" \
  -d '{"uuid":"nonexistent-uuid"}' http://localhost:8000/api/v1/deploy

{"message":"No resources found."}

💡 说明：正式使用时 uuid 取自应用/服务/数据库详情页的 UUID 或列举端点返回值，tag 为资源标签；force 布尔参数可强制无变更重建。实例暂无部署资源，故以参数校验与错误分支实测为准。

6.6 错误模型与权限边界（实测汇总）

同一端点在不同凭据/参数下的实测响应矩阵：

场景	实测请求	HTTP	响应体
无 Token	GET /api/v1/version	401	`{"message":"Unauthenticated."}`
错误 Token	GET /api/v1/version	401	`{"message":"Unauthenticated."}`
实例未开 API	携带有效 Token 调任意业务端点	200	`{"success":true,"message":"API is disabled."}`
read Token 调写端点	POST /api/v1/projects	403	`{"message":"Missing required permissions: write"}`
无 deploy 权限调部署	POST /api/v1/deploy	403	`{"message":"Missing required permissions: deploy"}`
deploy 端点缺参数	POST /api/v1/deploy	400	`{"message":"You must provide uuid or tag."}`
资源不存在	GET /api/v1/teams/999	404	`{"message":"Team not found."}`
端点路径不存在	GET /api/v1/healthcheck	404	`{"message":"Not found.","docs":"https://coolify.io/docs"}`

解读：401 是「没认上」，403 是「认上了但权限不足」，400 是「权限够但参数错」——排障先看状态码再对应处置；实例未开启 API 开关时的 API is disabled. 响应体最具迷惑性（HTTP 200 但业务全部不可用），见八、常见问题 Q1。另实测公开端点 GET /api/health（免认证，前缀无 v1）返回纯文本 OK，适合做存活探测。

七、注意事项

Token 只显一次：控制台生成时立即保存；遗失只能吊销重建。
权限最小化：只读集成用 read，触发部署的自动化再单独授 deploy，写权限仅给管理类脚本。
限流预算：默认 200 次/分钟按 Token 计，轮询型集成改用 Webhook 推送或调大 API_RATE_LIMIT。
API 与面板同源：API 端口即控制台端口（默认 8000），反向代理/防火墙策略对两者同时生效。
内置命令行的执行位置：必须经 $COMPOSE exec coolify php artisan ... 在平台服务内执行；在宿主机直接敲 php artisan 无意义。
清理类命令先诊断后执行：先跑 scheduled:diagnostics 与日志确认症状，再选择性执行 cleanup:*，避免误清正常队列。

八、常见问题

Q1：带上有效 Token 调用却返回 {"success":true,"message":"API is disabled."}？

实例的 API 开关未打开。实测该状态下所有业务端点都返回这句（HTTP 200），与 401 不同。处置：控制台 Settings → API 打开启用开关后重试，无需重启服务。

Q2：401 与 403 如何快速区分处置？

401（Unauthenticated.）查请求头格式是否为 Authorization: Bearer <Token>、Token 是否吊销/拼错；403（Missing required permissions: xxx）查 Token 权限勾选——实测 read Token 调 POST /projects 即返回 Missing required permissions: write，换含对应权限的 Token 即可。

Q3：团队明明存在，GET /api/v1/team/1 却 404？

路由是复数形式 /api/v1/teams/1（实测返回团队对象），单数 team/1 落到不存在的路径返回 {"message":"Not found.","docs":"https://coolify.io/docs"}。同类易混：健康探针是 /api/health（无 v1），而 /api/v1/healthcheck 实测 404 不存在。

Q4：平台有 OpenAPI 规范文件可拉取吗？

实测 GET /api/v1/openapi.json 返回 404；接口参考以官方文档站的 API Reference 页为准（参考链接 2）。

Q5：部署队列不动，先查什么？

顺序建议：$COMPOSE ps 看三服务健康 → horizon:status 确认队列工作器在跑 → scheduled:diagnostics 看心跳 → $COMPOSE logs --tail 50 coolify 看任务报错；确认卡死后按 5.5 节表格选 cleanup 命令处置。

九、参考链接

本专栏系列：《Coolify 介绍与选型指南》、《Coolify 4.4.6 Docker Compose 部署指南》、《Coolify 4.4.6 配置参数详解》
官方 API Reference：https://coolify.io/docs/api-reference （查询日期 2026-10-21）
官方文档站：https://coolify.io/docs （查询日期 2026-10-21）
GitHub 仓库：https://github.com/coollabsio/coolify （查询日期 2026-10-21）

Coolify 4.4.6 常用 CLI 命令与工具详解

Coolify 4.4.6 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、编排运维命令详解

4.1 状态总览：docker compose ls

4.2 服务明细：docker compose ps

4.3 配置核验：config --services 与 config --images

4.4 日志查看：logs --tail

4.5 健康复核：docker inspect

4.6 生命周期：restart / down / up --wait

五、平台内置命令行详解（php artisan）

5.1 调用方式与命令清单

5.2 管理员维护：root:reset-password / root:change-email

5.3 平台信息总览：about

5.4 计划任务诊断：schedule:list / scheduled:diagnostics

5.5 队列与清理命令族

六、REST API 详解（curl 实测）

6.1 端点与认证总览

6.2 版本探测：GET /api/v1/version

6.3 资源域列举（GET 实测）

6.4 写操作：项目增删（POST / DELETE 实测）

6.5 部署触发：POST /api/v1/deploy

6.6 错误模型与权限边界（实测汇总）

七、注意事项

八、常见问题

九、参考链接

4.1 状态总览：`docker compose ls`

4.2 服务明细：`docker compose ps`

4.3 配置核验：`config --services` 与 `config --images`

4.4 日志查看：`logs --tail`

4.5 健康复核：`docker inspect`

4.6 生命周期：`restart` / `down` / `up --wait`

5.2 管理员维护：`root:reset-password` / `root:change-email`

5.3 平台信息总览：`about`

5.4 计划任务诊断：`schedule:list` / `scheduled:diagnostics`