coolify-manager

Coolify 管理器

概述

此技能可通过官方 CLI 和直接 API 访问来管理 Coolify 部署。它提供用于诊断服务问题、修复常见 WordPress 问题、管理容器，以及在可自托管和云端 Coolify 实例上执行部署操作的工作流。

快速开始

检查先决条件

继续之前，请确认：

1. 用户可以访问 Coolify 实例（可自托管或云端）
2. 用户可以在其 Coolify 控制面板的 /security/api-tokens 获取 API 令牌
3. 用户知道其 Coolify 实例 URL

何时使用此技能

当用户出现以下情况时，调用此技能：

• 提到 Coolify
• 需要调试托管在 Coolify 上的宕机 WordPress 网站
• 想要检查服务运行状况、日志或状态
• 需要访问容器终端
• 想要管理部署、服务或应用程序
• Coolify 托管的网站出现 SSL 证书问题
• 需要修复 .htaccess 或 PHP 配置问题
• 想要管理环境变量或配置

安装与设置

第 1 步：安装 Coolify CLI

如果尚未安装 CLI，请使用随附的安装脚本：

bash scripts/install_coolify_cli.sh

这会将其安装到 ~/.local/bin/coolify。确保此目录位于用户的 PATH 中：

export PATH="$HOME/.local/bin:$PATH"

将此行添加到用户的 shell 配置文件（~/.bashrc、~/.zshrc 等）中以使其持久生效。

第 2 步：配置上下文

添加用户的 Coolify 实例：

coolify context add <context-name> <coolify-url> <api-token>

示例：

coolify context add production https://coolify.example.com YOUR_API_TOKEN

第 3 步：验证连接

coolify context verify

这将确认身份验证和连接均已成功。

健康检查

运行随附的健康检查脚本：

bash scripts/check_health.sh

此脚本会显示：

• CLI 版本
• 已配置的上下文
• 连接状态
• 可用资源
• 服务端状态

诊断问题

工作流决策树

当用户报告问题时：

1. 是否与服务可用性有关？

   • 网站宕机 → 检查服务状态
   • 容器无响应 → 检查日志
   • 部署失败 → 检查部署历史记录

2. 是否与 WordPress 有关？

   • 修改 .htaccess 后出现 500 错误 → 修复 .htaccess
   • REST API 警告 → 诊断 REST API
   • PHP 限制 → 更新 PHP 配置
   • SSL 问题 → 检查证书

3. 是否与性能或配置有关？

   • 需要更改环境变量 → 管理环境
   • 需要扩缩容 → 管理资源
   • 需要部署 → 触发部署

检查服务状态

# List all resources with status
coolify resource list

# Get detailed service info
coolify service get SERVICE_UUID

# Check specific application
coolify app get APP_UUID

状态指示：

• running:healthy - 服务运行正常
• running:unhealthy - 服务存在问题（检查日志）
• stopped - 服务未运行
• deploying - 正在部署

检查日志

# Application logs
coolify app logs APP_UUID

# Get more lines
coolify app logs APP_UUID --lines 500

对于包含多个组件的服务（例如带有数据库的 WordPress），请先获取服务详细信息，以确定组件 UUID：

coolify service get SERVICE_UUID --format json

然后从 JSON 输出中提取应用程序/数据库 UUID。

直接使用 API

当 CLI 无法提供所需功能时，请使用直接 API 调用。参考：references/api_endpoints.md

示例 - 获取详细的服务配置：

curl -H "Authorization: Bearer API_TOKEN" \
  https://coolify-instance.com/api/v1/services/SERVICE_UUID

管理服务

启动/停止/重启

# Services
coolify service start SERVICE_UUID
coolify service stop SERVICE_UUID
coolify service restart SERVICE_UUID

# Applications
coolify app start APP_UUID
coolify app stop APP_UUID
coolify app restart APP_UUID

# Databases
coolify database start DB_UUID
coolify database stop DB_UUID
coolify database restart DB_UUID

部署应用程序

# Deploy by UUID
coolify deploy APP_UUID

# Check deployment status
coolify deploy list APP_UUID

管理环境变量

# List env vars
coolify app env list APP_UUID

# Add/update env var
coolify app env set APP_UUID VAR_NAME "value"

# Delete env var
coolify app env delete APP_UUID VAR_NAME

# Restart to apply changes
coolify app restart APP_UUID

WordPress 故障排除

有关 WordPress 特定问题，请参考：references/wordpress_fixes.md

访问 WordPress 容器

通过 Coolify Web 终端（推荐）：

1. 前往 Coolify 控制面板
2. 打开 WordPress 服务
3. 点击侧边栏中的“Terminal”
4. 选择“wordpress”容器

通过 Docker（如果可以通过 SSH 访问）：

docker exec -it CONTAINER_NAME bash

WordPress 文件位于：/var/www/html/

常见 WordPress 问题

编辑 .htaccess 后网站宕机

这是一个需要立即处理的严重问题：

1. 访问容器终端（见上文）
2. 检查 .htaccess 文件：

   cd /var/www/html
   cat .htaccess
   

3. 找出有问题的行（通常是最后添加的行）
4. 删除有问题的行：

   sed -i '$d' /var/www/html/.htaccess
   

5. 服务应立即恢复

PHP 配置限制

提高 PHP 限制（max_input_vars、上传限制等）：

正确语法（不使用 = 符号，使用空格）：

echo "php_value max_input_vars 3000" >> /var/www/html/.htaccess
echo "php_value upload_max_filesize 64M" >> /var/www/html/.htaccess
echo "php_value post_max_size 128M" >> /var/www/html/.htaccess
echo "php_value memory_limit 256M" >> /var/www/html/.htaccess

验证：

tail -5 /var/www/html/.htaccess

REST API 误报

如果 Site Health 报告 REST API 不可用，但网站运行正常：

1. 从外部测试 REST API：

   curl https://site.com/wp-json/
   

2. 如果返回 JSON，则为误报——API 运行正常

3. 常见原因：Site Health 的环回测试被阻止，而非实际 API 被阻止

4. 验证 .htaccess 中的 HTTP_AUTHORIZATION：

   grep "HTTP_AUTHORIZATION" /var/www/html/.htaccess
   

   应包含：

   RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
   

如需详细的 WordPress 故障排查步骤，请将 references/wordpress_fixes.md 加载到上下文中。

SSL 证书问题

检查证书状态：

echo | openssl s_client -servername domain.com -connect domain.com:443 2>/dev/null | openssl x509 -noout -dates -subject -issuer

Coolify 使用 Traefik 和 Let's Encrypt 自动配置 SSL。证书会在到期前自动续订。

如果证书无效：

1. 检查 Coolify 仪表板 → 服务 → 域名
2. 重新生成 SSL 证书
3. 验证服务配置中的 Traefik 标签

高级操作

使用多个上下文

在 Coolify 实例之间切换：

# List contexts
coolify context list

# Switch context
coolify context use staging

# Perform operations
coolify deploy APP_UUID

# Switch back
coolify context use production

使用 JSON 输出执行批量操作

对 jq 等工具使用 --format json：

# Get all unhealthy services
coolify resource list --format json | jq '.[] | select(.status | contains("unhealthy"))'

# Get all running applications
coolify resource list --format json | jq '.[] | select(.type=="application" and .status=="running")'

# Extract service UUIDs
coolify service list --format json | jq -r '.[].uuid'

服务管理

# List servers with IPs/ports
coolify server list -s

# Validate server connection
coolify server validate SERVER_UUID

# Get server domains
coolify server domains SERVER_UUID

备份与恢复

# List databases
coolify database list

# Backup database
coolify database backup DB_UUID

# List backups
coolify database backups DB_UUID

参考资料

此技能包含全面的参考文档：

CLI 命令参考

当用户需要详细的 CLI 命令语法、标志或示例时，加载 references/cli_commands.md。

API 端点参考

执行直接 API 调用，或 CLI 不支持所需操作时，加载 references/api_endpoints.md。

WordPress 修复参考

排查 WordPress 特定问题（例如 .htaccess 问题、PHP 配置、REST API 问题或 SSL 证书）时，加载 references/wordpress_fixes.md。

常见模式

模式：服务已停止

1. 检查状态：coolify resource list
2. 获取详情：coolify service get UUID
3. 检查日志：coolify app logs APP_UUID
4. 根据日志定位问题
5. 修复问题（重启、更新配置、修复文件）
6. 验证：coolify resource list

模式：WordPress 网站问题

1. 访问容器终端（通过 Coolify 仪表板）
2. 转到 /var/www/html
3. 检查 .htaccess 是否存在语法错误
4. 测试 REST API：curl https://site.com/wp-json/
5. 如有需要，检查 PHP 配置
6. 如果进行了更改，重启服务

模式：部署问题

1. 列出最近的部署：coolify deploy list APP_UUID
2. 获取部署详情：coolify deploy get DEPLOY_UUID
3. 检查应用日志：coolify app logs APP_UUID
4. 修复已发现的问题（环境变量、配置、代码）
5. 触发新的部署：coolify deploy APP_UUID

此技能的故障排查

未找到 CLI

确保 PATH 中包含 ~/.local/bin：

echo $PATH | grep ".local/bin"

如果未找到：

export PATH="$HOME/.local/bin:$PATH"

将其添加到 shell 配置文件，以便永久生效。

连接失败

1. 验证 API 令牌是否有效（检查 Coolify 仪表板）
2. 检查 Coolify 实例 URL 是否正确
3. 测试手动连接：

   curl -H "Authorization: Bearer TOKEN" https://instance.com/api/v1/version
   

4. 如有需要，重新配置上下文

权限问题

确保 API 令牌具有所需权限：

• 状态/日志的读取权限
• 部署/重启的写入权限
• 触发部署的部署权限

在 Coolify 仪表板的 /security/api-tokens 中检查令牌权限。