🐳 Portainer 技能

    ╔═══════════════════════════════════════════════════════════╗
    ║                                                           ║
    ║   🐳  P O R T A I N E R   C O N T R O L   C L I  🐳      ║
    ║                                                           ║
    ║       通过 Portainer API 管理 Docker 容器                 ║
    ║            启动、停止、部署、重新部署                    ║
    ║                                                           ║
    ╚═══════════════════════════════════════════════════════════╝

“Docker 容器？我从我的睡莲叶上就能搞定。” 🐸

📖 此技能的作用是什么？

Portainer 技能 通过 Portainer 的 REST API，为您提供对 Docker 基础设施的完整控制能力——无需打开 Web UI，即可管理容器、堆栈（Stack）和部署任务。

功能特性：

• 📊 状态查询（status） — 检查 Portainer 服务端运行状态
• 🖥️ 环境端点（endpoints） — 列出所有已注册的 Docker 环境
• 📦 容器管理（containers） — 列出、启动、停止、重启容器
• 📚 堆栈管理（stacks） — 列出并管理基于 Docker Compose 的堆栈
• 🔄 重新部署（redeploy） — 从 Git 拉取最新代码并重新部署堆栈
• 📜 日志查看（logs） — 查看指定容器的标准输出与错误日志

⚙️ 使用要求

配置步骤

1. 从 Portainer 获取 API Token：

   • 登录 Portainer Web UI
   • 点击右上角用户名 → “My Account”（我的账户）
   • 滚动至 “Access tokens”（访问令牌）区域 → 点击 “Add access token”（添加访问令牌）
   • 复制生成的令牌（该令牌仅显示一次，关闭后不可再查看！）

2. 配置凭证信息：

   # 添加至 ~/.clawdbot/.env
   PORTAINER_URL=https://your-portainer-server:9443
   PORTAINER_API_KEY=ptr_your_token_here
   

3. 完成！ 🚀

🛠️ 可用命令

status — 检查 Portainer 服务端状态

./portainer.sh status

输出示例：

Portainer v2.27.3

endpoints — 列出全部环境端点

./portainer.sh endpoints

输出示例：

3: portainer (local) - ✓ online
4: production (remote) - ✓ online

containers — 列出容器

# 在默认端点（ID=4）上列出容器
./portainer.sh containers

# 在指定端点（如 ID=3）上列出容器
./portainer.sh containers 3

输出示例：

steinbergerraum-web-1    running    Up 2 days
cora-web-1               running    Up 6 weeks
minecraft                running    Up 6 weeks (healthy)

stacks — 列出全部堆栈（Stack）

./portainer.sh stacks

输出示例：

25: steinbergerraum - ✓ active
33: cora - ✓ active
35: minecraft - ✓ active
4: pulse-website - ✗ inactive

stack-info — 查看堆栈详细信息

./portainer.sh stack-info 25

输出示例（JSON 格式）：

{
  "Id": 25,
  "Name": "steinbergerraum",
  "Status": 1,
  "EndpointId": 4,
  "GitConfig": "https://github.com/user/repo",
  "UpdateDate": "2026-01-25T08:44:56Z"
}

redeploy — 拉取更新并重新部署堆栈 🔄

./portainer.sh redeploy 25

输出示例：

✓ Stack 'steinbergerraum' redeployed successfully

该操作将执行以下步骤：

1. 从 Git 仓库拉取最新代码
2. 如有必要，重建相关容器镜像
3. 重启整个堆栈

start / stop / restart — 容器生命周期控制

# 启动容器
./portainer.sh start steinbergerraum-web-1

# 停止容器
./portainer.sh stop steinbergerraum-web-1

# 重启容器
./portainer.sh restart steinbergerraum-web-1

# 显式指定端点（默认为 4）
./portainer.sh restart steinbergerraum-web-1 4

输出示例：

✓ Container 'steinbergerraum-web-1' restarted

logs — 查看容器日志

# 默认显示最后 100 行
./portainer.sh logs steinbergerraum-web-1

# 显示最后 50 行，并指定端点 ID（4）
./portainer.sh logs steinbergerraum-web-1 4 50

🎯 典型工作流示例

🚀 “部署网站更新”

# 合并 PR 后立即执行
./portainer.sh redeploy 25
./portainer.sh logs steinbergerraum-web-1 4 20

🔧 “调试容器问题”

./portainer.sh containers
./portainer.sh logs cora-web-1
./portainer.sh restart cora-web-1

📊 “系统概览检查”

./portainer.sh status
./portainer.sh endpoints
./portainer.sh containers
./portainer.sh stacks

🔧 故障排查

❌ “Authentication required / Repository not found”（需认证 / 仓库未找到）

问题原因： 堆栈重新部署时发生 Git 认证失败

解决方案： 堆栈需配置 repositoryGitCredentialID 参数。本脚本会自动从已有堆栈配置中读取该值，无需手动干预。

❌ “Container not found”（容器未找到）

问题原因： 输入的容器名称不匹配

解决方案： 请使用 ./portainer.sh containers 输出中的**完整精确名称**：

• 必须包含完整名称，例如：steinbergerraum-web-1，而非 steinbergerraum
• 容器名称区分大小写

❌ “PORTAINER_URL and PORTAINER_API_KEY must be set”（必须设置 PORTAINER_URL 和 PORTAINER_API_KEY）

问题原因： 凭证未正确配置

解决方案：

# 添加至 ~/.clawdbot/.env
echo "PORTAINER_URL=https://your-server:9443" >> ~/.clawdbot/.env
echo "PORTAINER_API_KEY=ptr_your_token" >> ~/.clawdbot/.env

🔗 与 Clawd 集成示例

"Redeploy the website"
→ ./portainer.sh redeploy 25

"Show me running containers"
→ ./portainer.sh containers

"Restart the Minecraft server"
→ ./portainer.sh restart minecraft

"What stacks do we have?"
→ ./portainer.sh stacks

📜 更新日志

🐸 致谢

  @..@
 (----)
( >__< )   "Containers are just fancy lily pads
 ^^  ^^     for your code to hop around!"

作者：Andy Steinberger（由他的 Clawdbot 青蛙 Owen 🐸 协助完成）
底层支持：Portainer API
所属项目：Clawdbot Skills Collection