vexdock-api

Vexdock API

Vexdock 没有 CLI。API 就是完整的接口；仪表板只是它的一个客户端。以下所有操作都使用 curl 和 jq。

设置

需要两个环境变量。缺少时请向用户询问；绝不要回显令牌。

export VEXDOCK_URL=https://panel.example.com   # no trailing slash
export VEXDOCK_TOKEN=...                        # System → Settings → API tokens, shown once

每个 shell 中只需定义一次，并在每次调用时使用：

vx() { curl -sS -H "Authorization: Bearer $VEXDOCK_TOKEN" -H 'Content-Type: application/json' "$VEXDOCK_URL$@"; }

验证：vx /api/me 会返回账户信息；vx /api/health（公开接口）会报告 {"status":"healthy"} 或 503。

在已通过会话身份验证的上下文中创建令牌，或请用户执行： POST /api/tokens {"name":"agent"} → 201 {"token":{...},"value":"..."}； value 之后不会再出现。DELETE /api/tokens/{id} 会撤销令牌。

约定

• Bearer 令牌无需 CSRF 标头。会话 Cookie 需要同源；不要在脚本中使用。
• 请求体使用 JSON，Content-Type: application/json。未知字段会被拒绝，并返回 400。
• 错误格式：{"error":{"code","message","details"?}}。错误代码：INVALID_REQUEST 400、 UNAUTHORIZED 401、CROSS_ORIGIN 403、NOT_FOUND 404、CONFIRMATION_REQUIRED 428、 CONFLICT 409、TASK_RUNNING 409、UNHEALTHY 409、GIT_PROVIDER_IN_USE 409、PROJECT_NOT_EMPTY 409、 DATABASE_NOT_RUNNING 409、STUDIO_UNSUPPORTED 400、QUERY_FAILED 400、 GIT_PROVIDER_UNAVAILABLE 400、GIT_PROVIDER_ERROR 502、CERTIFICATE_FAILED 502、INTERNAL 500。429 由 Nginx 返回，不包含上述错误格式。
• ID 是不透明字符串。通过列出资源来解析名称对应的 ID；绝不要猜测。
• 除非指定 ?environment={id}，否则项目路由会作用于项目的默认环境。 适用于 deploy、stop、services、services/export、deployments。
• 部署会立即返回 202。轮询 GET /api/deployments/{id}，直到 deployment.status 为 success、failed 或 cancelled（期间为 queued/running），也可以流式读取 .../events。
• exec 或任务 run 的退出码非零时仍会返回 200；请读取 exit_code。
• 破坏性调用：删除卷和 cleanup/volumes 需要 ?confirm=true；删除环境时，指定 ?volumes=true 也会删除数据。只有项目不包含任何服务时，才能删除该项目（409 PROJECT_NOT_EMPTY）。传入任一标志前，请先与用户确认。每次变更都会记录审计日志。
• 流使用 SSE：使用 curl -N 并读取 event:/data: 行。终端使用 WebSocket；请改用 POST .../exec。

查找内容

vx /api/projects | jq '.[] | {id, name, environments: [.environments[] | {id, name, is_default}]}'
vx /api/projects/$PROJECT/services | jq '.[] | {id, name, provider, state, status, health}'
vx /api/projects/$PROJECT/services?environment=$ENV
vx /api/docker/containers | jq '.[] | {id, name, state, managed}'
vx /api/domains | jq '.[] | {id, hostname, service, project_id}'
vx /api/tasks | jq '.[] | {id, name, schedule, service_name, project_name}'

部署并等待

DEP=$(vx /api/services/$SERVICE/deploy -X POST | jq -r .id)     # or /api/projects/$PROJECT/deploy
until [ "$(vx /api/deployments/$DEP | jq -r .deployment.status)" != "queued" ] && \
      [ "$(vx /api/deployments/$DEP | jq -r .deployment.status)" != "running" ]; do sleep 3; done
vx /api/deployments/$DEP | jq '{status: .deployment.status, steps: [.steps[] | {name, status}]}'

无需轮询，改为实时查看日志：curl -N -H "Authorization: Bearer $VEXDOCK_TOKEN" $VEXDOCK_URL/api/deployments/$DEP/events。

• 在排队或运行期间，使用 POST /api/deployments/{id}/cancel 取消部署。
• POST /api/deployments/{id}/rollback 会重新部署该部署记录的提交（没有记录时返回 400）。
• POST /api/projects/{id}/stop 等同于 compose down；卷会保留。

在服务中运行命令

vx /api/services/$SERVICE/exec -d '{"command":"php artisan migrate --force"}'
# → {"exit_code":0,"output":"..."}

shell 为 sh（默认）或 bash。支持 shell 语法（管道、&&、环境变量）。 命令在服务的容器中运行，不会在主机上运行。10 分钟后调用会放弃等待，但命令仍会继续运行，因此重试前请先检查；输出超过 1 MiB 时会保留末尾部分。容器必须处于运行状态。

查询数据库（Studio）

仅支持目录中的数据库；管理器通过 compose 网络连接，无需发布端口。

vx /api/services/$SERVICE/studio | jq '.schemas[] | {name, tables: [.tables[].name]}'
vx "/api/services/$SERVICE/studio/rows?schema=public&table=users&limit=20&sort=id&order=desc"
vx /api/services/$SERVICE/studio/query -d '{"schema":"public","query":"select count(*) from users"}'
# → {"columns":["count"],"rows":[["42"]],"affected":0,"duration_ms":3,"truncated":false}
vx /api/services/$SERVICE/studio/changes -d '{"schema":"public","table":"users","updates":[{"key":{"id":"7"},"values":{"name":"Ada"}}]}'

• 每个单元格都是字符串或 null；非 UTF-8 字节会以 \x 十六进制形式返回，MongoDB 字段则使用宽松模式的 Extended JSON。
• where 是经过 URL 编码的 JSON [{"column","op","value"}]；op 可为：eq neq gt gte lt lte contains starts_with is_null is_not_null。
• limit 为 1–500；查询结果最多返回 1,000 行（truncated）。key 为空的表为只读。
• 查询内容可以是 SQL、MongoDB 的单条 Extended JSON 命令（{"find":"users","limit":5}）， 或 Valkey 的单行命令（架构为 db0，表为 keys）。命令会在自动提交模式下运行：执行写入操作前，请先与用户确认。
• QUERY_FAILED 会包含数据库自身的错误消息。

无需流水线的生命周期管理

vx /api/services/$SERVICE/start   -X POST
vx /api/services/$SERVICE/stop    -X POST
vx /api/services/$SERVICE/restart -X POST
vx /api/docker/containers/$CONTAINER/restart -X POST   # any container, managed or not

日志和统计信息

curl -N -H "Authorization: Bearer $VEXDOCK_TOKEN" "$VEXDOCK_URL/api/services/$SERVICE/logs"   # SSE: log, end
curl -N -H "Authorization: Bearer $VEXDOCK_TOKEN" "$VEXDOCK_URL/api/services/$SERVICE/stats"  # SSE: stats
vx "/api/services/$SERVICE/metrics?window=1h"     # 30m 1h 6h 24h 7d
vx "/api/system/metrics?window=24h"
vx /api/system/info

项目和服务

vx /api/projects -d '{"name":"shop"}'                                    # 201
vx /api/services/$SERVICE -X PATCH -d '{"auto_deploy":true}'
vx /api/projects/$PROJECT -X DELETE                                      # only once it has no services

# git application
vx /api/projects/$PROJECT/services -d '{"name":"web","provider":"github","repository_url":"https://github.com/o/r","branch":"main"}'
# image
vx /api/projects/$PROJECT/services -d '{"name":"cache","provider":"image","image":"redis:7-alpine"}'
# database from the catalog (image, volume, credentials generated)
vx /api/projects/$PROJECT/services -d '{"name":"db","database":{"engine":"postgres","version":"17-alpine"}}'
vx /api/services/$SERVICE/database                                       # connection details
# pasted compose fragment
vx /api/projects/$PROJECT/services -d '{"name":"worker","provider":"raw","compose_fragment":"image: x\ncommand: run"}'

vx /api/services/$SERVICE -X PATCH -d '{"branch":"release"}'
vx /api/services/$SERVICE -X DELETE                                      # named volume is kept
vx /api/engines; vx /api/engines/postgres/versions

创建和编辑操作不会启动容器：之后再部署。provider 的值为 unconfigured、github|gitlab|bitbucket|gitea|git、image 或 raw。Git 凭据：credential_kind 为 none|token|ssh_key，加上 credential_secret （仅写入）；或者，对于已连接的提供方，使用 git_provider_id + owner + repository（GET /api/git-providers、.../{id}/repositories）。

变量

分为三层，均支持 GET | PUT，并且整体写入（PUT 会替换整个集合）：

vx /api/projects/$PROJECT/variables        # every environment of the project
vx /api/environments/$ENV/variables        # this environment only; wins on collision
vx /api/services/$SERVICE/variables        # this service only
vx /api/services/$SERVICE/variables -X PUT -d '{"variables":[{"key":"APP_ENV","value":"production","is_secret":false},{"key":"APP_KEY","value":"...","is_secret":true}]}'

先读取，再合并，然后执行 PUT；如果 PUT 只提交部分列表，其余条目会被删除。 更改需要经过部署才能应用到容器。

环境

vx /api/projects/$PROJECT/environments
vx /api/projects/$PROJECT/environments -d '{"name":"staging","branch":"develop"}'
vx /api/environments/$ENV -X PATCH -d '{"branch":""}'   # "" = each service follows its own branch
vx /api/environments/$ENV -X DELETE                     # ?volumes=true; default env answers 400
vx "/api/projects/$PROJECT/deploy?environment=$ENV" -X POST

域名

vx /api/domains -d '{"project_id":"'$PROJECT'","service":"web","hostname":"shop.example.com","container_port":3000,"https_enabled":true,"redirect_https":true}'
vx /api/domains/$DOMAIN/certificate -X POST              # issue/renew now; 502 CERTIFICATE_FAILED with reason
vx /api/domains/$DOMAIN -X DELETE

可选参数：environment_id、certificate_source letsencrypt|custom（+ certificate_pem、private_key_pem）。创建或更新操作可能会在虚拟主机已保存但证书未保存时返回 warning；请通过 certificate 重试。

定时任务

vx /api/services/$SERVICE/tasks -d '{"name":"prune","schedule":"0 3 * * *","timezone":"Europe/Warsaw","command":"php artisan model:prune"}'
vx /api/tasks/$TASK -X PATCH -d '{"enabled":false}'
vx /api/tasks/$TASK/run -X POST                          # answers with the finished run; 409 TASK_RUNNING if busy
vx "/api/tasks/$TASK/runs?limit=5"
vx /api/tasks/$TASK -X DELETE

五字段 cron 表达式，以及 @hourly|@daily|@weekly|@monthly|@yearly。管理器停机期间错过的定时触发不会补执行。运行超过 30 分钟的任务会被放弃，不过其进程可能仍在运行。

Docker 清理

vx /api/docker/cleanup                                   # dry run: bytes per kind
vx /api/docker/cleanup/images -X POST                    # containers | images | networks | build-cache
vx "/api/docker/cleanup/volumes?confirm=true" -X POST    # ask the user first
vx /api/docker/images/pull -d '{"reference":"nginx:1.27"}'
vx "/api/docker/images/$IMAGE?force=true" -X DELETE
vx "/api/docker/volumes/$NAME?confirm=true" -X DELETE
vx /api/docker/containers/$CONTAINER/remove?force=true -X POST

系统

vx /api/system/settings                                  # PUT writes the whole object; cloudflare_api_token is write-only
vx /api/system/backup -X POST                            # ?volumes=true is slow and large; snapshot holds the master key
vx /api/system/backups; vx /api/system/backups/2026-01-05T031500 -X DELETE
vx /api/system/version; vx /api/system/version/check -X POST   # check_error set: latest is stale, says why
vx /api/system/update -X POST -d '{}'                    # latest on track; refuses 409 UNHEALTHY, 400 while check_error is set
vx /api/system/update -X POST -d '{"version":"v0.1.0-beta.100"}'   # a named tag skips the lookup
vx /api/system/update/status                             # phase: idle|backup|pulling|restarting|done|rolled-back
vx /api/system/certificates
vx /api/registries -d '{"name":"ghcr","url":"ghcr.io","username":"u","password":"..."}'   # login is verified on create

POST /api/system/update 会重建管理器：在 restarting 期间，API 预计会中断一分钟；请持续轮询 update/status。

工作方式

1. 通过列表查询解析 ID；报告时在 ID 旁标出名称。
2. 优先使用范围最小的调用：优先部署服务而非项目，优先使用 exec 而非重启。
3. 对 PUT 端点（变量、设置）先读取，再修改，然后写入。
4. 说明破坏性调用会删除哪些内容，并在使用 confirm=true / volumes=true 前征得同意。
5. 部署后报告 status；如果有失败步骤，也要报告其名称；步骤日志位于事件流中。
6. 切勿回显 VEXDOCK_TOKEN、credential_secret、注册表密码或 ?secrets=true 导出内容。

完整的响应格式参考见 Vexdock 仓库中的 docs/api.md；GET /api/health 和 GET /api/system/version 是仅有的公开读取接口。