catalog/repos/ajmcclary--coolify-manager.md

# Coolify 部署管理技能

`Coolify` `部署管理` `WordPress` `Claude技能` `服务诊断`

# Coolify Manager

一个全面的 [Claude 技能](https://www.anthropic.com/news/skills)，用于管理和排查 Coolify 部署问题。该技能扩展了 Claude Code 的能力，提供针对 Coolify 服务器管理、WordPress 故障排查、服务诊断和部署操作的专业知识。

## 功能特性

- **🚀 自动化 CLI 安装** - 自动安装并配置官方 Coolify CLI，支持平台检测
- **🏥 健康诊断** - 快速检查服务、容器和连接的健康状态
- **🔧 WordPress 故障排查** - 针对 Coolify 上常见 WordPress 问题的专项工作流
- **📊 服务管理** - 监控、重启并管理应用、服务和数据库
- **🐳 容器访问** - 访问容器终端并管理 WordPress 文件
- **🔐 SSL 证书管理** - 检查并排查 SSL 证书问题
- **📚 完整文档** - 完整的 API 和 CLI 参考指南
- **🔄 多实例支持** - 通过上下文切换管理多个 Coolify 实例

## 安装

### Claude Code 用户

1. 下载 `coolify-manager` 技能
2. 将其放置在 Claude 技能目录中
3. Claude 将自动检测并加载该技能

### 手动安装

```bash
# 克隆仓库
git clone https://github.com/ajmcclary/Coolify-Manager.git
cd Coolify-Manager

# 安装 Coolify CLI
bash scripts/install_coolify_cli.sh

# 添加到 PATH（如果尚未添加）
export PATH="$HOME/.local/bin:$PATH"

# 配置你的 Coolify 实例
coolify context add production https://your-coolify-instance.com YOUR_API_TOKEN

# 验证连接
bash scripts/check_health.sh
```

## 快速上手

### 前置条件

- 可访问的 Coolify 实例（自托管或云端）
- 从 Coolify 控制台 `/security/api-tokens` 获取的 API 令牌
- Coolify 实例 URL

### 基本用法

```bash
# 检查服务状态
coolify resource list

# 获取服务详情
coolify service get SERVICE_UUID

# 查看日志
coolify app logs APP_UUID

# 部署应用
coolify deploy APP_UUID

# 重启服务
coolify service restart SERVICE_UUID
```

### WordPress 故障排查

访问 WordPress 容器：

```bash
# 通过 Coolify 控制台：服务 → 终端 → 选择 "wordpress" 容器

# 检查 .htaccess
cd /var/www/html
cat .htaccess

# 修复 PHP 配置
echo "php_value max_input_vars 3000" >> /var/www/html/.htaccess

# 测试 REST API
curl https://your-site.com/wp-json/
```

## 包含内容

### 脚本

- **`install_coolify_cli.sh`** - 自动化 CLI 安装脚本，支持平台检测（macOS/Linux，x86_64/ARM64）
- **`check_health.sh`** - 全面检查 CLI、上下文、连接和资源的健康状态

### 参考文档

- **`api_endpoints.md`** - 包含示例的完整 Coolify API 参考
- **`cli_commands.md`** - 包含工作流的完整 CLI 命令文档
- **`wordpress_fixes.md`** - 常见问题的 WordPress 故障排查指南

### 文档说明

- **`SKILL.md`** - 包含工作流和决策树的主技能定义
- **`CLAUDE.md`** - 使用本技能的开发指南
- **`README.md`** - 本文件

## 目录结构

```
coolify-manager/
├── README.md                      # 入门指南
├── SKILL.md                       # 主技能文档
├── CLAUDE.md                      # 开发指南
├── scripts/
│   ├── install_coolify_cli.sh    # CLI 安装脚本
│   └── check_health.sh           # 健康检查脚本
└── references/
    ├── api_endpoints.md          # API 参考
    ├── cli_commands.md           # CLI 指南
    └── wordpress_fixes.md        # WordPress 故障排查
```

## 常见任务

### 诊断服务问题

1. **检查状态**：`coolify resource list`
2. **获取详情**：`coolify service get UUID`
3. **查看日志**：`coolify app logs APP_UUID`
4. **修复问题**：根据日志和错误信息处理
5. **重启服务**：`coolify service restart SERVICE_UUID`
6. **验证结果**：`coolify resource list`

### 修复 WordPress 问题

**修改 .htaccess 后站点宕机：**
```bash
# 通过 Coolify 控制台访问容器终端
cd /var/www/html
sed -i '$d' .htaccess  # 删除最后一行
```

**提高 PHP 限制：**
```bash
echo "php_value max_input_vars 3000" >> /var/www/html/.htaccess
echo "php_value upload_max_filesize 64M" >> /var/www/html/.htaccess
```

**检查 SSL 证书：**
```bash
echo | openssl s_client -servername your-site.com -connect your-site.com:443 2>/dev/null | openssl x509 -noout -dates
```

### 管理多个环境

```bash
# 列出上下文
coolify context list

# 切换到测试环境
coolify context use staging
coolify deploy APP_UUID

# 切换回生产环境
coolify context use production
```

## 环境要求

- **Coolify CLI**：v1.0.3+（通过脚本自动安装）
- **平台**：macOS（darwin）或 Linux
- **架构**：x86_64（amd64）或 ARM64
- **Shell**：bash 或 zsh
- **工具**：curl、tar（用于安装）

## 获取 Coolify API 令牌

1. 进入 Coolify 控制台
2. 前往 `/security/api-tokens`
3. 创建具有适当权限的新令牌：
   - 读取权限：用于状态/日志查看
   - 写入权限：用于部署/重启操作
   - 部署权限：用于触发部署

## 故障排查

### CLI 未找到

确保 `~/.local/bin` 已添加到 PATH：

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

### 连接失败

1. 验证 API 令牌是否有效
2. 检查 Coolify 实例 URL 是否正确
3. 手动测试：
   ```bash
   curl -H "Authorization: Bearer YOUR_TOKEN" https://your-instance.com/api/v1/version
   ```

### 服务不健康

1. 查看服务日志：`coolify app logs APP_UUID`
2. 通过 Coolify 控制台访问容器终端
3. 检查容器特定的日志和配置
4. 重启服务：`coolify service restart SERVICE_UUID`

## 贡献指南

本技能旨在沉淀真实的 Coolify 管理工作流，欢迎贡献以下内容：

- 更多故障排查模式
- 随 Coolify 演进的新 CLI 命令
- WordPress 专项修复方案
- 文档改进

## 许可证

MIT 许可证 - 详见仓库说明

## 相关资源

- [Coolify 官方文档](https://coolify.io/docs)
- [Coolify CLI GitHub](https://github.com/coollabsio/coolify-cli)
- [Coolify API 参考](https://coolify.io/docs/api-reference/api/)
- [Claude 技能](https://www.anthropic.com/news/skills)

## 致谢

基于真实 Coolify 管理和故障排查工作流，使用 [Claude Code](https://claude.com/claude-code) 创建。

---

**适用对象**：管理 VPS 部署的 Coolify 用户  
**兼容版本**：Coolify v4.0.0-beta.380+  
**CLI 版本**：1.0.3