【免费下载链接】ccg-workflow多模型协作工作流引擎 — /ccg:go 一个命令AI 自动分析意图、选择策略、编排 Codex Gemini Claude 协作执行项目地址https://gitcode.com/gh_mirrors/cc/ccg-workflow点击查看免费下载导读本文是 ccg-workflow 仓库中bt-panel技能位于 templates/skills/bt-panel的实战操作手册完整收录其 references/recipes.md 中沉淀的真实运维场景纯前端静态站更新、Node.js/PHP 后端部署、单文件热修复、数据库迁移、远程诊断与基于自动备份的回滚。读完本文你将能够只凭一个宝塔面板地址 32 位 API 密钥在无需 SSH、无需 rsync的前提下完成从部署、重启到回滚的完整线上运维闭环并能针对签名失败、IP 白名单、字段名版本差异等高频故障快速定位修复。bt-panel是 ccg-workflow 随 v3.5.1 引入的独立技能见 README.zh-CN.md同批技能还包括seo-page-builder、adsense-site-auditor。它由三个可执行文件组成通用 API 客户端 bt_client.py、一键部署编排器 bt_deploy.py以及站点别名配置模板 sites.example.json。本文所有命令均以这三个文件为运行基础并会结合源码解释其底层行为让你不仅会用还知道为什么。一、前置工具链与凭据约定在套用下文任何一条食谱之前先确认工具链就位。仓库中的bt-panel技能安装后位于~/.claude/skills/ccg/bt-panel/目录结构如下见 SKILL.md~/.claude/skills/ccg/bt-panel/ ├── SKILL.md # 技能指南 ├── bt_client.py # 核心 API 客户端 通用 CLItest/sites/ls/cat/put/exec/sql … ├── bt_deploy.py # 一键部署器tar→upload→extract→sql→restart→cleanup ├── sites.example.json # 站点别名配置示例复制为 sites.json 使用 └── references/ ├── api-reference.md # 宝塔 v11 API 接口速查踩过的坑都在这 └── recipes.md # 实战食谱更新前端 / PHP / Node / 回滚 …本文主体仓库测试 skills-hygiene.test.ts 专门断言bt_client.py、bt_deploy.py、sites.example.json三个文件随技能一同发布也就是说这套食谱不是纸上谈兵——脚本与文档一起被打包分发。凭据的三种提供方式# 方式 1环境变量一次性 export BT_URLhttps://panel.example.com:8888 export BT_KEYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 方式 2CLI 参数 python3 bt_client.py --panel https://1.2.3.4:8888 --key XXX test # 方式 3sites.json 别名长期使用推荐--alias name从源码看build_client()bt_client.py的取值优先级是--panel/--key显式参数 环境变量BT_URL/BT_PANEL/BT_KEY/BT_API_KEY--alias对应站点配置bt_deploy.py同理bt_deploy.py。load_site_alias()bt_client.py依次查找三个候选文件$BT_SITES_JSON环境变量指定路径、~/.claude/skills/bt-panel/sites.json、~/.bt-sites.json先到先用。⚠️ 安全提醒API 密钥等同于服务器 root 权限sites.json必须进入.gitignore绝不可提交到 git 跟踪的文件中recipes.md 的最佳实践一节有具体操作下文详述。连通性自检python3 bt_client.py test # 返回里附带变体探测结果 # _skill_detected: {os: linux, variant: bt, major: 11, shell: bash}test()在 bt_client.py 中实现它调用/system?actionGetSystemTotal并触发panel_info探测返回面板版本、系统信息与_skill_detected字段。该探测结果决定后续所有接口的选择策略这也是食谱中大量命令能一套脚本通吃宝塔 v7–v11 / aaPanel / Windows 面板的底层原因。二、七大实战场景从部署到回滚的完整命令模板场景 1更新一个纯前端静态站Vue/React dist特点无状态、需要完整替换、无服务重启、可以清空目标目录。直接命令行方式python3 bt_deploy.py \ --local ./dist \ --remote /www/wwwroot/h5.example.com \ --clean \ --owner www:www \ --exclude *.map或做成 alias 长期复用h5-frontend: { panel: https://1.2.3.4:8888, key: xxxx, local: ~/projects/myapp-h5/dist, remote: /www/wwwroot/h5.example.com, clean: true, exclude: [*.map] }python3 bt_deploy.py --alias h5-frontend源码剖析--clean在部署时先执行find {remote} -mindepth 1 -delete清空目标目录但保留目录本身bt_deploy.py配合tar -xzf ... --strip-components1解压到目标目录bt_deploy.py最后按--owner默认www:www执行chown -R修正属主bt_deploy.py。静态站没有进程需要重启因此不需要restart字段——这是它与后端场景最大的区别。场景 2更新 Node.js 后端pm2 管理python3 bt_deploy.py \ --alias myapp-api \ --backup \ --restart cd /www/wwwroot/myapp-api npm install --production pm2 restart myapp-apialias 配置myapp-api: { panel: https://1.2.3.4:8888, key: xxxx, local: ~/projects/myapp-api, remote: /www/wwwroot/myapp-api, database: myapp_db, backup: true, exclude: [node_modules, .git, .env.local, *.log], restart: [ cd /www/wwwroot/myapp-api npm install --production --silent, cd /www/wwwroot/myapp-api pm2 restart myapp-api || pm2 start ecosystem.config.js ] }关键点解读exclude排除node_modules、.git、.env.local、*.log本地依赖与敏感环境变量不进 tar 包线上依赖通过restart里的npm install --production现场安装restart可以是字符串或字符串数组Deployer.restart_service()bt_deploy.py按顺序逐条执行pm2 restart myapp-api || pm2 start ecosystem.config.js的写法保证进程在就重启、不在就按配置拉起backup: true会在部署前对远端目录做 tar.gz 备份这是场景 7 回滚的基础默认排除清单在 merge_cfg() 中兜底node_modules、.git、.DS_Store、*.log、*.pyc、__pycache__即使你不写exclude也不会把依赖和日志打包。场景 3更新 PHP 站FastAdmin/ThinkPHPjys-backend: { panel: https://1.2.3.4:8888, key: xxxx, local: ~/projects/mysite-php, remote: /www/wwwroot/mysite-php, database: jys, backup: true, exclude: [vendor, .git, runtime/*, *.log, .idea], restart: [ cd /www/wwwroot/mysite-php find runtime/temp -name *.php -delete 2/dev/null; true, systemctl reload nginx ] }关键点解读PHP 框架FastAdmin/ThinkPHP 等的runtime目录是编译缓存部署后清理临时文件并用; true保证即便 find 无匹配也不中断命令链systemctl reload nginx让 PHP 改动即时生效PHP-FPM 版本不同时也可按需改为systemctl restart php-fpm-74参考 sites.example.json 中demo-php的写法database: jys配合--backup会在部署时对数据库做备份详见场景 5。场景 4只改一两个配置文件热修复无需重部署直接put或write# 覆盖单文件本地有改动 python3 bt_client.py put ./server/config/prod.ts /www/wwwroot/app/server/config/ # 直接写一行本地没改动想快速改 python3 bt_client.py write /www/wwwroot/app/.env API_URLhttps://new.api.com DEBUGfalse # 重启服务 python3 bt_client.py exec pm2 restart app --cwd /www/wwwroot/app源码剖析put走的是BtClient.upload()bt_client.py底层调用/files?actionupload超过 4MB 自动按 4MB 分片chunk_size4*1024*1024空文件则用SaveFileBody兜底write走的是BtClient.write_file()bt_client.py它实现了双重自动兜底若返回指定文件不存在/not exist就先CreateFile再重试若返回FILE_SAVE_ERR Permission denied/tmp sticky bit 或跨用户写冲突就先DeleteFile再CreateFile再重试。这就是为什么食谱里敢直接write覆盖.env而不用担心失败exec走exec_shell()--cwd指定执行目录默认/root--wait控制最长等待秒数默认 300。场景 5数据库迁移带备份# 1. 先备份exec 方式避开 ToBackup 的面板任务队列 python3 bt_client.py exec \ mysqldump -u\$USR -p\$PWD mydb /www/backup/mydb_$(date %Y%m%d_%H%M%S).sql \ --cwd /tmp --wait 600 # 2. 执行迁移 SQL python3 bt_client.py sql mydb --from-file ./migrations/2026-04-10-add-column.sql # 3. 回滚预案记下备份路径必要时 python3 bt_client.py sql mydb --from-file /www/backup/mydb_xxx.sql或用bt_deploy.py的集成sql字段把迁移融入部署{ sql: ./migrations/2026-04-10.sql, database: mydb }源码剖析sql子命令对应sql_execute()bt_client.py其执行策略是三通道自适应先试面板 API/database?actionSqlExecutev7–v10 多数可用v11 通常被拦截返回指定参数无效Linux/macOS/aaPanel 退回 shell mysql CLI heredoc凭据自动从/data?actiongetDatatabledatabases查出_lookup_db_credentials()bt_client.pymysql 二进制按/www/server/mysql/bin/mysql→/www/server/mariadb/bin/mysql→/usr/local/mysql/bin/mysql→command -v mysql→mysql逐级探测密码通过MYSQL_PWD环境变量传入不出现在进程列表heredoc delimiter 用 uuid 动态生成防止 SQL 内容碰撞注入Windows 面板退回 cmd 等价方案临时文件 type重定向heredoc 在 cmd 下不可用。sql_execute会自动为 SQL 补尾部分号--from-file读取本地 SQL 文件内容再执行。bt_deploy.py的apply_sql()bt_deploy.py把sql字段SQL 字符串或.sql文件路径接入部署流水线与database字段配对使用在解压后、重启前执行。场景 6远程诊断查日志 / 查进程 / 查端口# 查 pm2 状态 python3 bt_client.py exec pm2 status --cwd /root # 查最近的 nginx error log python3 bt_client.py exec tail -200 /www/wwwlogs/myapp.example.com.error.log # 查端口占用 python3 bt_client.py exec ss -tlnp | grep :3000 # 磁盘占用 top 10 python3 bt_client.py exec du -sh /www/wwwroot/* | sort -hr | head -10这些命令全部复用exec_shell()的远程执行通道。其实现要点bt_client.py命令会被自动包装上结束标记echo __BT_DONE__轮询/files?actionGetExecShellMsg直到标记出现从而拿到完整的 stdoutstderr 累积输出下发接口按panel_info.major自适应v11 先试ExecShellv11 改名后的新接口v7–v10 先试ExecShellMsg失败自动回退另一个actions元组的顺序首次下发后sleep 0.8s再开始轮询——这是给宝塔创建/tmp/panelExec.pl留时间避免FILE_SHELL_EMPTY误报宝塔 Linux/aaPanel 的 shell 以root身份执行因此可以ss、tail系统日志、读写任意路径。场景 7回滚基于自动备份部署时--backup会生成/www/backup/bt_skill/站点名_timestamp.tar.gz。回滚即选备份包 → 清空目标 → 解压还原 → 修正属主 → 重启服务# 1. 列出备份 python3 bt_client.py exec ls -la /www/backup/bt_skill/ # 2. 选一个备份包解压回目标位置 python3 bt_client.py exec SITE/www/wwwroot/myapp.example.com BAK/www/backup/bt_skill/myapp.example.com_20260410_120000.tar.gz find $SITE -mindepth 1 -delete tar -xzf $BAK -C $(dirname $SITE) chown -R www:www $SITE pm2 restart myapp 源码剖析备份由Deployer.backup_remote()bt_deploy.py完成——mkdir -p /www/backup/bt_skill后用tar -czf打包远端目录-C parent name保证解包时还原目录层级备份路径可被backup_dir配置项覆盖默认/www/backup/bt_skill。若目标目录不存在则跳过备份并给出NO_TARGET警告。recipes.md 特意提醒绝不直接用rm -rf删除/www/wwwroot/*先--backup再--clean见 SKILL.md 的安全铁律。三、故障排查8 个高频线上问题与修复签名校验失败 / Invalid signature可能原因API 密钥复制错了多一个空格、少一个字符本地机器时间漂移与面板服务器差 60 秒面板设置里 API 密钥被改过了排查# 对时 ntpdate pool.ntp.org # Linux sudo sntp -sS time.apple.com # macOS # 验证密钥登宝塔面板 → 设置 → API 接口 → 查看密钥底层原理宝塔签名算法是request_token md5(request_time md5(api_key))bt_client.py 的_sign()方法。因为request_time取本地 Unix 秒客户端与服务器时间偏差超过 60 秒会被面板拒绝这就是对时能解决签名失败的原因。IP 未在白名单原因宝塔 API 接口默认只放特定 IP。修复登宝塔面板 → 设置 → API 接口IP 白名单添加本机公网 IPcurl ifconfig.me查临时方案加0.0.0.0放行全部仅测试环境❓指定参数无效(指定参数无效!)原因API 接口的字段名在宝塔不同版本间变化。案例ExecShellMsg→ v11 改名为ExecShellSqlExecute→ v11 可能拦截用 shell mysql 代替调试方法仿效——遍历候选字段组合打印每次返回找到当前版本认的字段名for candidate in ({shell: cmd, path: /tmp}, {cmd: cmd}, ...): r c.request(/files?actionNewAction, candidate) print(candidate, →, r)宝塔 v11.6.0 实测环境中所有已知正确字段名已整理在 references/api-reference.md字段名版本差异对照表、shell 下发/取回接口、SQL 兜底方案一应俱全。配方本身已内置该自适应exec_shell()按主版本号选择接口并自动回退sql_execute()失败自动降级 shell 通道。FILE_SAVE_ERR Permission denied原因/tmp的 sticky bitdrwxrwxrwt让SaveFileBody无法覆写其他进程创建的文件。修复bt_client.write_file()已自动 deleterecreate 兜底见场景 4 的源码剖析或改用子目录/tmp/bt_work/xxx代替直接/tmp/xxx或走/files?actionupload不受此问题影响⏳FILE_SHELL_EMPTY/ exec 永远 timeout原因 A用错了接口名。v11 必须是/files?actionExecShell不是ExecShellMsg。原因 B首次 poll 太快/tmp/panelExec.pl还没被宝塔创建。修复bt_client.exec_shell()已处理——首次下发后sleep 0.8s再轮询收到FILE_SHELL_EMPTY时sleep 1后继续对应 api-reference.md 中正确的轮询姿势。Access denied for user xxx(MySQL)原因数据库用户/密码错。排查# 1. 从面板查看实际凭据 python3 bt_client.py dbs # 2. bt_client.sql_execute 默认会自动查凭据如果还报错 # 可能是 accept 限制了 localhost面板 → 数据库 → 权限设置 python3 bt_client.py exec grep -r $DB_NAME /etc/mysql 2/dev/null; cat /etc/my.cnf | head -30说明dbs子命令即get_databases()返回的每条记录含username、password、accept字段sql_execute的_lookup_db_credentials()正是从这里自动取凭据。上传文件为 0 字节/ upload 状态异常可能原因文件大小超过面板 nginx 限制默认 1GB分片上传中某一片失败磁盘空间不足排查python3 bt_client.py exec df -h / /tmp /www python3 bt_client.py exec cat /www/server/nginx/conf/proxy.conf | grep client_maxpm2 重启没生效排查# 1. 确认 pm2 已启动 python3 bt_client.py exec pm2 status --cwd /root # 2. 确认你用的是宝塔用户的 pm2宝塔用 www 用户时需要 sudo -u www python3 bt_client.py exec which pm2; pm2 --version # 3. 强制重启 python3 bt_client.py exec pm2 kill; pm2 start /www/wwwroot/app/ecosystem.config.js提示宝塔 Linux 面板的 shell 以 root 执行但部分环境下 pm2 是 www 用户安装的因此可能需要sudo -u www或直接确认which pm2指向的二进制。四、最佳实践让部署变成可重复的工程流程 组织 sites.json# 1. 复制模板 cp ~/.claude/skills/ccg/bt-panel/sites.example.json ~/.claude/skills/ccg/bt-panel/sites.json # 2. 设置权限防手滑 commit chmod 600 ~/.claude/skills/ccg/bt-panel/sites.json # 3. 加入全局 .gitignore echo sites.json ~/.gitignore_globalsites.example.json仓库版见 templates/skills/bt-panel/sites.example.json本身就是一份完整的字段字典它演示了demo-fullstackNode 全栈 数据库 backup restart、demo-static静态站 clean、demo-phpPHP nginx/php-fpm 重启三类典型别名每个别名可用的字段包括panel、key、local、remote、database、owner、backup、exclude、restart、clean、sql、backup_dir。文件头部的_readme数组还写明了路径优先级$BT_SITES_JSON~/.claude/skills/ccg/bt-panel/sites.json~/.bt-sites.json。仓库的 skills-hygiene.test.ts 会持续扫描技能目录确保打包发布的内容里不含任何真实的 API 密钥、公网 IP 或个人路径——你在本地实践时也应对照这一标准。 部署前必看# 先干跑 python3 bt_deploy.py --alias myapp --dry-run # 查远端当前状态最近改动时间 python3 bt_client.py exec find /www/wwwroot/myapp -type f -mtime -1 | head -20 # 检查重启脚本在本地能跑通 bash -n ecosystem.config.js--dry-run的实现值得说明Deployer各阶段在self.dry为真时只打印将要做什么而不真正执行连通测试仍会真实执行因为需要它确认凭据有效备份路径、tar 包远端路径照常计算见 bt_deploy.py 中各方法的if self.dry: return分支。 部署后核验# 1. HTTP 探活 python3 bt_client.py exec curl -I -s http://localhost:3000/health # 2. 日志尾部 python3 bt_client.py exec tail -50 /www/wwwroot/myapp/logs/app.log # 3. pm2 状态 python3 bt_client.py exec pm2 status这对应 SKILL.md 响应流程中的核验环节执行后通过curl -I探活或cat .env读回确认改动真实生效再向上汇报目标、改动范围与服务状态。⚡ 多站点并发部署# 用 并发 wait 汇总 python3 bt_deploy.py --alias site1 python3 bt_deploy.py --alias site2 python3 bt_deploy.py --alias site3 wait echo all done注意事项同一面板并发 exec 会互相覆盖/tmp/panelExec.pl宝塔用单文件存储上一次 shell 输出但upload和SaveFileBody是独立的所以不同站点并发 OK同站点并发可能有 exec 日志串。如需并发执行且要传递结果自己写文件区分your_cmd /tmp/my_out_$(uuidgen).log 21见 api-reference.md。五、从食谱到流水线bt-panel 在 ccg-workflow 中的位置bt-panel不只提供手动命令它还作为 ccg-workflow 的独立技能被注册到技能注册表skill-registry.ts中user-invocable: true意味着它可被/ccg:bt-panel斜杠命令直接唤起见 README.zh-CN.md 的技能表。安装时installer.ts 会把templates/skills/完整复制到~/.claude/skills/ccg/并扫描user-invocable技能自动生成斜杠命令skill-registry.ts。因此recipes.md 中的每条命令模板既可以被你手工执行也可以作为 Agent 在收到更新线上 / 部署到服务器 / 跑一下 SQL / 重启 pm2等意图时的执行依据——配合 SKILL.md 中的响应流程识别 → 连通 → 盘点 → 决策 → 执行 → 核验 → 上报形成一条从用户一句话到线上服务完成更新的自动化链路。结语recipes.md 的价值不在于能跑通而在于它把真实建站运维中反复踩过的坑v11 接口改名、sticky bit、轮询时序、并发串台逐一沉淀成了可复用的命令与配置模板。本文在完整继承这 7 大场景、8 类故障排查与 4 组最佳实践的基础上进一步对照 bt_client.py 与 bt_deploy.py 的源码解释了每条命令底层的接口选择、自动兜底与安全机制。遇到更细的接口参数问题可随时查阅 api-reference.md 的完整接口速查表。赞分享【免费下载链接】ccg-workflow多模型协作工作流引擎 — /ccg:go 一个命令AI 自动分析意图、选择策略、编排 Codex Gemini Claude 协作执行项目地址https://gitcode.com/gh_mirrors/cc/ccg-workflow点击查看免费下载相关推荐宝塔面板远程操控实战基于 ccg-workflow 的 bt-panel 技能实现免 SSH 部署与运维宝塔面板远程操控实战基于 ccg workflow 的 bt panel 技能实现免 SSH 部署与运维 本指南以 ccg workflow 仓库内置的 btccg-workflow bt-panel 技能实战通过宝塔/aaPanel HTTP API 远程运维与一键部署服务器ccg workflow bt panel 技能实战通过宝塔/aaPanel HTTP API 远程运维与一键部署服务器 本文深入解析 ccg workflo人工智能AI 应用开发工具CLIAI Agentdsh-pluginDeepSeekccg-workflow bt-panel 实战食谱通过宝塔 API 远程部署、热修复与回滚的完整操作手册ccg workflow bt panel 实战食谱通过宝塔 API 远程部署、热修复与回滚的完整操作手册 本篇基于 ccg workflow 仓库中 bt人工智能AI 应用开发工具CLIAI Agentdsh-pluginDeepSeek上一篇RePKGWallpaper Engine壁纸资源提取与转换的终极指南下一篇GitHub中文插件终极指南5分钟让GitHub界面说中文新手也能快速上手创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
