name: portainer
description: 通过 Portainer API 管理 Docker 容器与堆栈。可列出容器、启动/停止/重启、查看日志，以及从 Git 重新部署堆栈。
metadata: {"clawdbot":{"emoji":"🐳","requires":{"bins":["curl","jq"],"env":["PORTAINER_API_KEY"]},"primaryEnv":"PORTAINER_API_KEY"}}

🐳 Portainer 技能

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

"Docker 容器？让我从我的荷叶上来处理它们。" 🐸

📖 功能概述

Portainer 技能 让你能够通过 Portainer 的 REST API 来管理你的 Docker 基础设施。无需使用 Web 界面即可管理容器、堆栈和部署。

核心功能：
- 📊 状态 — 检查 Portainer 服务器状态
- 🖥️ 端点 — 列出所有 Docker 环境
- 📦 容器 — 列出、启动、停止、重启容器
- 📚 堆栈 — 列出和管理 Docker Compose 堆栈
- 🔄 重新部署 — 从 Git 拉取代码并重新部署堆栈
- 📜 日志 — 查看容器日志

⚙️ 前置要求

配置步骤

1. 从 Portainer 获取 API 令牌：

   • 登录 Portainer Web 界面
   • 点击用户名 → 我的账户
   • 滚动到"访问令牌" → 添加访问令牌
   • 复制令牌（之后将无法再次查看！）

2. 配置凭据：
   bash # 添加到 ~/.clawdbot/.env 文件 PORTAINER_URL=https://你的-portainer-服务器:9443 PORTAINER_API_KEY=ptr_你的令牌_这里

3. 准备就绪！ 🚀

🛠️ 命令详解

status — 检查 Portainer 服务器

./portainer.sh status

输出示例：

Portainer v2.27.3

endpoints — 列出环境端点

./portainer.sh endpoints

输出示例：

3: portainer (本地) - ✓ 在线
4: production (远程) - ✓ 在线

containers — 列出容器

# 列出默认端点 (4) 上的容器
./portainer.sh containers

# 列出特定端点上的容器
./portainer.sh containers 3

输出示例：

steinbergerraum-web-1    运行中    运行 2 天
cora-web-1               运行中    运行 6 周
minecraft                运行中    运行 6 周 (健康)

stacks — 列出所有堆栈

./portainer.sh stacks

输出示例：

25: steinbergerraum - ✓ 活跃
33: cora - ✓ 活跃
35: minecraft - ✓ 活跃
4: pulse-website - ✗ 未激活

stack-info — 查看堆栈详情

./portainer.sh stack-info 25

输出示例：

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

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

./portainer.sh redeploy 25

输出示例：

✓ 堆栈 'steinbergerraum' 重新部署成功

此操作将：
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

输出示例：

✓ 容器 'steinbergerraum-web-1' 已重启

logs — 查看容器日志

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

# 最后 50 行
./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

🔧 故障排除

❌ "需要认证 / 仓库未找到"

问题： 堆栈重新部署时出现 Git 认证错误

解决方案： 堆栈需要 repositoryGitCredentialID 参数。脚本会自动从现有堆栈配置中读取此信息。

❌ "容器未找到"

问题： 容器名称不匹配

解决方案： 使用 ./portainer.sh containers 输出的确切名称：
- 使用完整名称：steinbergerraum-web-1 而非 steinbergerraum
- 名称区分大小写

❌ "必须设置 PORTAINER_URL 和 PORTAINER_API_KEY"

问题： 凭据未配置

解决方案：

# 添加到 ~/.clawdbot/.env 文件
echo "PORTAINER_URL=https://你的服务器:9443" >> ~/.clawdbot/.env
echo "PORTAINER_API_KEY=ptr_你的令牌" >> ~/.clawdbot/.env

🔗 与 Clawd 集成示例

"重新部署网站"
→ ./portainer.sh redeploy 25

"显示正在运行的容器"
→ ./portainer.sh containers

"重启 Minecraft 服务器"
→ ./portainer.sh restart minecraft

"我们有哪些堆栈？"
→ ./portainer.sh stacks

📜 更新日志

🐸 致谢

  @..@
 (----)
( >__< )   "容器不过是让你的代码
 ^^  ^^     跳来跳去的精致荷叶罢了！"

作者： Andy Steinberger (在他的青蛙助手 Clawdbot Owen 🐸 的帮助下)
技术支持： Portainer API
所属项目： Clawdbot 技能集