CapRover 管理技能

CapRover 是一个自托管的平台即服务（PaaS），它封装了 Docker Swarm。它提供 REST API 以实现完整的应用生命周期管理。

快速设置

始终从身份验证开始：

python
import urllib.request, json, ssl

ctx = ssl.createdefaultcontext()
ctx.check_hostname = False
ctx.verifymode = ssl.CERTNONE # CapRover 上常见自签名证书

BASE = https:// # 例如 https://captain.example.com

def api(path, data=None, token=None, timeout=60):
body = json.dumps(data).encode() if data else None
headers = {Content-Type: application/json}
if token:
headers[x-captain-auth] = token
req = urllib.request.Request(f{BASE}{path}, data=body, headers=headers)
resp = urllib.request.urlopen(req, context=ctx, timeout=timeout)
return json.loads(resp.read())

token = api(/api/v2/login, {password: })[data][token]

所有端点请参见 references/api.md。现成的辅助类请参见 scripts/caprover.py。

核心工作流

1. 创建应用

python
api(/api/v2/user/apps/appDefinitions/register,
{appName: myapp, hasPersistentData: False}, token)

如果应用需要持久卷，请设置 hasPersistentData: True。

2. 从 Docker 镜像部署

python
api(/api/v2/user/apps/appDefinitions/update,
{appName: myapp, imageName: nginx:latest}, token)

api(/api/v2/user/apps/appData/myapp/redeploy,
{appName: myapp, gitHash: }, token)

3. 从自定义 Dockerfile 部署（在主机上构建）

将 captain-definition、Dockerfile 和支持文件打包成 .tar.gz，然后 POST：

python

captain-definition（必须位于 tar 根目录）：

{schemaVersion: 2, dockerfilePath: ./Dockerfile}

with open(app.tar.gz, rb) as f:
tar_data = f.read()

boundary = ----FormBoundaryCaprover
body = (
f--{boundary}\r\n
fContent-Disposition: form-data; name=sourceFile; filename=app.tar.gz\r\n
fContent-Type: application/octet-stream\r\n\r\n
).encode() + tar_data + f\r\n--{boundary}--\r\n.encode()

req = urllib.request.Request(
f{BASE}/api/v2/user/apps/appData/myapp,
data=body,
headers={
Content-Type: fmultipart/form-data; boundary={boundary},
x-captain-auth: token,
},
)
resp = urllib.request.urlopen(req, context=ctx, timeout=180)

这会在 CapRover 主机上原生构建镜像——对于预构建的 amd64 镜像无法运行的 ARM64 主机至关重要。

4. 配置端口、环境变量、卷

python
api(/api/v2/user/apps/appDefinitions/update, {
appName: myapp,
envVars: [{key: MY_VAR, value: hello}],
ports: [{hostPort: 25565, containerPort: 7777}],
volumes: [{containerPath: /data, volumeName: myapp-data}],
instanceCount: 1,
}, token)

⚠️ 端口更新问题：ports 字段更新有时会在 CapRover 上返回 HTTP 500（已知问题）。解决方法：在应用创建时一次性设置端口，或使用 serviceUpdateOverride。

5. 高级 Docker Swarm 设置（serviceUpdateOverride）

用于标准 API 未暴露的设置——卷挂载、自定义 DNS、资源限制：

python
override = json.dumps({
TaskTemplate: {
ContainerSpec: {
Mounts: [{
Type: volume,
Source: captain--myapp-data, # CapRover 命名：captain---
Target: /data
}]
}
}
})

api(/api/v2/user/apps/appDefinitions/update,
{appName: myapp, serviceUpdateOverride: override}, token)

⚠️ 将 serviceUpdateOverride 设置为 （空字符串）会清除它并移除所有 Docker Swarm 覆盖设置，包括卷挂载。

6. 读取日志

python

构建日志（部署后）

r = api(/api/v2/user/apps/appData/myapp, token=token)
build_lines = r[data][logs][lines]

运行时日志（运行中容器的标准输出）

r = api(/api/v2/user/apps/appData/myapp/logs, token=token) raw_logs = r[data][logs]

ARM64 / 多架构注意事项

如果 CapRover 主机是 ARM64（uname -m 返回 aarch64）：

• - 不要使用仅支持 amd64 的预构建镜像——它们会静默失败或崩溃并显示 exec 格式错误
• 在主机上从 Dockerfile 构建（上述工作流 #3）以获得原生 ARM64 镜像
• 对于需要 Mono 的应用（例如 Linux ARM64 上的 Windows .exe 文件）：在 Dockerfile 中安装 mono-runtime，并使用 mono ./App.exe 作为入口点
• 在脚本中运行时检测架构：$(uname -m) 在 ARM64 上返回 aarch64

常见问题

症状	可能原因	修复方法
端口更新时 HTTP 500	CapRover 问题	在应用创建时设置端口，或使用 serviceUpdateOverride
容器崩溃，无日志

架构镜像错误（arm64 上的 amd64） | 在主机上从 Dockerfile 构建 | | 端口开放但服务器无响应 | 服务器仅监听 127.0.0.1 | 检查服务器绑定地址；使用 0.0.0.0 | | 重启后世界/数据丢失 | 无卷挂载 | 添加带 Mounts 的 serviceUpdateOverride | | 日志为空 | 应用将日志写入文件而非标准输出 | 覆盖入口点以重定向到标准输出 | | API 中 volumes: [] 但数据持久存在 | serviceUpdateOverride 持有挂载——API 和 Swarm 状态不一致 | 检查 serviceUpdateOverride，而不仅仅是应用定义 |

节点 / 集群信息

python
r = api(/api/v2/user/system/info, token=token)
nodes = r[data][nodes]

参考

• - 完整 API 端点列表 + 请求/响应格式：references/api.md
• 可复用的 Python 辅助类：scripts/caprover.py