开发工具链 on 扎塔-Zata

Blender 详解：奥斯卡和 AI Agent 为什么都选了它

Tue, 15 Sep 2026 10:30:00 +0800

2025 年 3 月，洛杉矶，第 97 届奥斯卡颁奖礼。最佳动画长片颁给了拉脱维亚的《Flow》（猫猫的奇幻漂流）——一个小团队、低成本做出来的电影。有一个技术细节容易被忽略：它全程在 Blender 里制作，渲染用的是 Blender 自带的实时引擎 EEVEE，不是渲染农场里跑几十小时的路径追踪，是游戏级的实时渲染。

差不多同一时期，AI 圈里另一个和 Blender 有关的东西也在涨：blender-mcp，一个把 Blender 变成 AI 助手可操控工具的开源项目，如今 GitHub 星数超过 2.8 万。

一部奥斯卡获奖电影，和一个 AI Agent 工具链，选了同一款免费软件。这篇文章回答三个问题：Blender 是什么、它为什么好、以及它为什么恰好站在了 AI 的位置上。先说结论：它的赢法不是"免费打败收费"，而是三件事的叠加——一个不追求租金的基金会、三次把能力拉平的技术解锁，以及一套恰好为 AI Agent 准备好的架构。

一、一个应用，就是一整条管线

先看主流 3D 制作的工作方式：Maya 管建模动画，ZBrush 管雕刻，Substance 管贴图，After Effects 管合成——一条管线由四五个付费软件拼起来。Blender 走的是相反的路，把全部环节装进同一个应用：

建模与雕刻：多边形建模、雕刻模式（4.x 版本大幅重写）、重拓扑；
UV 与纹理：UV 编辑、程序化纹理节点；
绑定与动画：骨骼、约束、驱动器、非线性动画编辑器；
物理模拟：流体、烟雾、布料、毛发、刚体；
渲染：Cycles（路径追踪，2011 年起）与 EEVEE（实时渲染，2019 年起）双引擎；
后期：合成器、视频剪辑、运动跟踪；
2D 动画：Grease Pencil——正是《蜘蛛侠：纵横宇宙》用来处理线稿的工具。

▲ Blender 的工作区：3D 视口、大纲视图、属性面板、时间线同屏。顶部标签栏本身就是一份流程清单——建模、雕刻、渲染、合成、脚本、视频剪辑都在同一个应用里。图：Ogat / Wikimedia Commons（GPL）

一体化带来的真正价值是环节之间不丢信息。在 Blender 里改了模型的拓扑，UV 和材质自动跟着走，不需要导出导入、不需要对版本、不需要在四个软件之间来回搬运资产。

两个渲染器值得单独说。Cycles 是路径追踪器，负责"照片级"，2011 年随 2.61 版本加入；EEVEE 是实时渲染器，负责"秒出"，随 2019 年的 2.8 版本登场，2024 年的 4.2 LTS 把它重写为 EEVEE Next，实时渲染第一次有了可用的全局光照——《Flow》全片用的就是它。

二、为什么免费还能做到这个水平

Blender 的起点是破产。1998 年 Ton Roosendaal 创立 NaN 公司开发 Blender，2002 年公司经营失败进入清算，Blender 差点作为资产被卖掉。Roosendaal 先成立非营利的 Blender Foundation，然后在当年 7 月 18 日发起「Free Blender」行动：向社区募资 10 万欧元，一次性付给债权人，换取源码以 GPL 协议开源。7 周，钱凑齐了。2002 年 9 月 7 日，Blender 正式开源。

▲ Ton Roosendaal，Blender 创始人与 Blender Foundation 主席，摄于 2018 年。2002 年他发起众筹，用 10 万欧元把 Blender 的源码从破产清算里赎了出来。图：Blender / Wikimedia Commons（CC BY 3.0）

这个故事决定了此后二十年的一切。因为 GPL 加非营利基金会，Blender 没有股东要回报、没有订阅要续费、也没有"把基础功能拆出来单独收费"的动机。它的钱来自 Blender Development Fund——一种订阅制资助：个人按月捐，企业按档赞助，NVIDIA、AMD、Intel、Meta、Epic 等公司长期在名单上。维基百科口径下，Blender Institute 的规模是 26 名全职员工加 12 名自由职业者。

这个体量在大厂眼里不值一提，但它二十年只做一件事：把 3D 全流程做进同一个免费应用。对比之下，Maya 的订阅一年要上千美元，而 Blender 从建模到渲染到剪辑一分钱不花。对个人创作者和中小团队，“免费"不是省钱——它决定的是项目能不能启动。

基金模式还有一个副产品：Blender Studio 用"做电影来磨工具”。从 2008 年的《Big Buck Bunny》到 2021 年的《Sprite Fright》，每一部开放电影都是新功能的试验场，成片和工程文件全部开源，反哺社区教程和素材库。

▲ Blender Studio 的开放电影《Sprite Fright》（2021）海报。Blender 用真实制作推动引擎和工具开发，成片与资产全部开源。图：Blender Studio / Wikimedia Commons（CC BY 4.0）

三、三次解锁：从能用，到好用，到工业级

免费只是入场券。“开源软件难用"的标签，是 Blender 自己花十几年撕掉的。

时间	版本	解锁了什么
2019 年 7 月	2.80	界面重做、左键选择、行业兼容键位、EEVEE 实时渲染登场
2021 年 2 月	2.92	Geometry Nodes 几何节点，程序化建模免费化
2025 年 11 月	5.0	ACES 色彩管线、HDR、NanoVDB 体积渲染、材质编译提速 4 倍

2019 年的 2.8，把"难用"改掉了。 在此之前，Blender 的键位和交互是自成一体的体系，新用户的第一道门槛不是建模而是适应界面。2.8 一次性对齐了行业惯例——左键选择、兼容键位、重新设计的界面，并让实时渲染器 EEVEE 首次登场。这是它从"能用"走向"好用"的起点。

2021 年的 Geometry Nodes，把 Houdini 的能力免费化了。 2.92 引入的几何节点让程序化建模——散布、阵列、非破坏性修改——变成连节点就能完成的事。这是影视和游戏里最贵的一类技能，此前基本是 Houdini 的专属领地。

▲ Blender 2.92 的 Geometry Nodes 编辑器，正在演示石子散布（Pebble Scattering）。程序化建模从数千美元一年的软件专属能力，变成了免费功能。图：Simon Thommes / Wikimedia Commons（CC BY 4.0）

2025 年的 5.0，把色彩和渲染追上了工业标准。 2025 年 11 月 18 日发布的 Blender 5.0 补齐了影视工业最挑剔的两块短板：原生支持 ACES 色彩管线与 HDR 广色域，以及用 NanoVDB 重构的体积渲染——烟雾、火焰的内存占用大幅下降。同期 EEVEE 的材质编译速度最高提升 4 倍。

工业界的接受度有一条清晰的证据链：《Next Gen》（2018）由 Tangent Animation 全流程用 Blender 制作；《蜘蛛侠：纵横宇宙》（2023）用 Grease Pencil 处理线稿；《RRR》的 VFX 团队 Makuta VFX 是 Blender 用户；Ubisoft 动画工作室宣布自 2020 年起转向 Blender。到《Flow》拿下奥斯卡最佳动画长片，这条链条闭了环。

▲ 用 Cycles 渲染器渲染的 Lone Monk 演示场景（Blender 2.92 官方演示文件）。路径追踪让"照片级"渲染跑在了消费级显卡上。图：Carlo Bergonzini / Monorender，PantheraLeo135953 渲染 / Wikimedia Commons（CC BY 4.0）

四、AI 为什么说它"用起来方便”

Blender 在 AI 圈的走红，有它自己独立的逻辑，和它在传统 3D 圈的积累不是一回事。把"AI 用 Blender"拆开看，是四个具体机制在起作用。

它把点击任务降级成了代码任务。 Blender 的 Python API（bpy）覆盖了界面上几乎每一个操作。对语言模型来说这是本质区别：写 Python 是主场能力，点击 GUI 不是。用 Blender，Agent 不需要"看"界面、算坐标、点按钮，直接输出脚本——等于绕开了 computer-use 最难的两个环节：像素观察和坐标点击。

观察便宜，验证干净。 blender --background --python script.py 全程无 GUI，Agent 的观察通道是 stdout 和 bpy.data 里的结构化场景数据，不是截图。这带来两个好处：一个脚本可以批量完成几十个操作，一次工具调用搞定；验证变成"读数据"——bpy.data.objects['Cube'].location 是精确、可复现的验证态，不存在"两张截图看起来一样但其实状态变了"的模糊地带。

几乎没有反自动化摩擦。 免费、开源、无许可证服务器、无加密狗、可容器化。更关键的是从 3.4 版本起 pip install bpy——Blender 本身就是一个 Python 依赖包，Agent 调它和调 numpy 没有区别。Maya 做不到：需要运行实例加授权激活。

语料的正反馈。 网上有海量的 Blender Python 代码——教程、插件、问答，模型的先验很强，生成脚本成功率高；用的人越多，语料越多。这个循环闭源商业软件很难复制。

生态层面，blender-mcp 把 MCP 协议桥接进了 Blender 侧边栏：装好插件，Claude 这类 AI 助手可以通过自然语言直接建模、改材质、跑渲染。

▲ Blender 侧边栏里的 BlenderMCP 面板（Port 9876）。启动服务后，AI 助手通过 MCP 协议直接驱动 Blender 执行建模、材质和渲染操作。图：ahujasid/blender-mcp（MIT）

2026 年这套模式已经铺开——Unity MCP、UnrealClaude、Cocos Creator MCP 都进入可用状态。Agent 的角色也在变：当下的实践是把整条管线交给 Agent 调度（概念生成 → 3D 重建 → 自动绑定 → Blender 导入清理 → 动画驱动 → 导出引擎格式），Blender 当落地执行的那个节点。

有一个坑值得单独提醒：bpy.ops 加 mode_set 是一套上下文状态机——必须先切到正确模式（比如 POSE）才能操作骨骼，否则 operator 直接失败。这是 Agent 写 Blender 脚本最常见的故障。好的一面是报错是文本，能进自我修复循环；换成 GUI 点击，失败往往是静默的，没法自动修。

五、AI+3D 管线里的位置

“AI 用 Blender"要分成两件事：一是生成式 AI 直接产出 3D 资产（Tripo、Meshy 这类模型），Blender 做精修和落地；二是 Agent 操控 Blender（上一节）。前者在 2026 年出现了一个关键变化。

拓扑瓶颈被突破。 2026 年 9 月 1 日，VAST 发布 3D 基础模型 Tripo P2.0——据北京经开区官网报道，这是全球首个原生生成四边面拓扑网格的 3D 基座模型，最多 25k 四边面或 50k 三角面，边缘流更合理、大平面更干净、支持自动分件。这件事的分量在于：此前 AI 生成的是三角面汤，重拓扑成本和重新建模差不多，所以只能做静态背景道具；原生四边面意味着生成结果可以直接进游戏引擎和动画绑定管线——AI 3D 从玩具变成生产工具的分界线，就在这里。

国内大厂已经在跑工业化管线。腾讯光子内部打磨 4 年的 Light AI 于 2026 年 6 月对外亮相，把"概念探索 → 2D 三视图 → 3D 白模 → 材质 → 骨骼动作迁移"整合成一套平台；腾讯 VISVISE 的动作生成能力已用在 90 多款游戏里（含《和平精英》《王者荣耀》），支持文生动画和"3-5 个关键帧生成 10 秒动画”。

成本侧的数据同样直白：摩根士丹利测算生成式 AI 可削减 3A 游戏开发成本约 44%（投行测算，当量级参考）；国内游戏研发端的 AI 普及率已达 86.36%（音数协口径）。

Blender 在这条管线里的位置由此清晰：免费让它没有授权摩擦，headless 让它能进服务器批处理，bpy 让它能被脚本和 Agent 驱动。它就是那个"AI 生成 → 自动清理 → 导出引擎格式"的落地中枢——决定这个位置的是它的架构，而不是某个新功能。

六、它不强的部分

把话说全，Blender 的短板同样明确：

大规模角色动画与绑定，Maya 仍是行业标准，Blender 在复杂角色管线上的工具链还不够顺；
高端雕刻，ZBrush 仍是天花板，Blender 的雕刻模式进步很大但没有到取代的程度；
CAD 精度（NURBS、参数化实体建模）基本没有，这块要交给 Fusion、Rhino、Plasticity；
大而全本身也是代价——每一项都不是同类最强，专业环节的团队依然会配置专业软件；
硬件门槛在提高：5.0 起不再支持老 GPU（GeForce 900 系之前、GCN 4 之前、Kaby Lake 之前）。

还有一个容易被 AI 叙事掩盖的风险：制作端省钱不等于市场端接受。据 Game Oracle 统计，明确声明使用 AI 的游戏发售首月评论数平均减少 52.6%。AI 管线降低的是生产成本，不是市场风险。

七、我的判断

Blender 火过两次，逻辑是同一件事：它把 3D 生产的成本结构改了。 第一次对内——免费和一体化解决了"能不能做"；第二次对外——它的架构（bpy 全覆盖、headless、pip 可安装、无授权摩擦）恰好是 AI Agent 时代最需要的形态。

这个判断成立的前提是：Blender 保持基金会治理和 GPL。只要这个前提在，它在"AI 3D 落地点"这个位置上的优势就是结构性的，不是某个模型升级能带走的。真正的变量在 AI 生成质量那一侧——如果生成的模型哪天真的开箱即用，精修环节会缩水；但"谁来批量调度、自动清理、导出管线"这个问题，仍然需要一个 Blender 这样的中枢。

总结

Blender 用基金会 + GPL 的模式，把建模到渲染到剪辑的全流程做进了同一个免费应用，这是它二十年最大的结构性优势；
2019 的 2.8、2021 的 Geometry Nodes、2025 的 5.0 三次解锁，让它从"能用"走到"工业级"，《Flow》拿下奥斯卡是这条链条的闭环时刻；
对 AI Agent 而言，它的核心价值是 bpy 全覆盖、headless 执行、pip install bpy 和可读的验证态——把"点击任务"变成了"代码任务"，而后者正是大模型的主场；
想上手：从 Blender 官网下载 4.2 LTS 或 5.0，跟着一个甜甜圈教程走完全流程，就能体会"一个应用一条管线"的含义；想玩 AI 驱动，装 blender-mcp 加 Claude，从让它改一个材质开始。

Herdr 详解：给 AI Agent 用的终端运行时

Tue, 15 Sep 2026 10:30:00 +0800

如果你同时开着三个 Claude Code、两个 Codex，再挂一台远程机器的构建任务，你大概经历过这几件事：某个 Agent 早就停下来等你批准命令，你却在另一个标签页里刷了两分钟；SSH 断了一下，跑了一半的活没了；想知道"现在到底哪个窗口在干活"，只能一个个切过去看。

Herdr 就是冲这些事来的。它的官方定位是"The runtime your coding agents live on"——不是替代 Agent，而是给 Agent 提供它们运行于其中的那层终端基础设施。用一句话概括：Herdr 是把 tmux 按 Agent 的工作方式重新设计了一遍。

这篇文章基于我本机装的 herdr 0.9.0（stable 通道，protocol 22），把它的用法、概念模型和配置讲清楚，命令和输出都是实际跑出来的。（9 月 15 日补充：右键转发、复制模式、会话恢复的全景、插件从装到写、手机用法、中文输入法开关。同日二次补充：9.6.7 装了一个真插件的完整实录。）

一、它到底是什么，和 tmux 差在哪

Herdr 是 tmux 一脉的 后台 server + 前端 client 架构：client 只是一个"显示器 + 键盘"，真正的 pty、进程、布局都在 server 里。但它在几个地方做了明确的 Agent 化改造：

维度	tmux	Herdr
基本目的	保住终端会话	托管 AI Agent 的工作区
组织单位	session → window → pane	workspace → tab → pane
状态感知	无，pane 里有什么全靠肉眼看	每个 pane 有语义状态：`working` / `blocked` / `done` / `idle`
总览	逐个 window 切	侧边栏跨所有 workspace 汇总 Agent 列表
控制接口	`tmux` 命令	CLI + 本地 socket JSON API，给 Agent 用的
多机	要自己拼 ssh	`--remote` / 已保存机器，本地与远程同一视图
鼠标	基本可用	一等公民，点击/拖拽/右键菜单全能

原话是"不包装、不替换 Agent，只接管它们的终端"。所以 Claude Code、Codex、Cursor、OpenCode、Grok 这些还是原来那些，只是被放进了 Herdr 管理的工作区里——Herdr 能识别它们、给它们状态打标、允许它们互相说话。

技术上是 Rust 单二进制，没有 Electron，终端后端用 libghostty（Ghostty 的终端库），Windows 走 ConPTY。装完就是一个约等于 tmux 的东西，但多了 Agent 那一层。

想先看动起来是什么样，官方 README 里有一段二十来秒的演示（视频直链）：多个 Agent 在分屏里并行跑，侧边栏实时显示谁 blocked、谁 idle、谁 done，鼠标点着切窗格。下文用到的几张截图就是从这段演示和官方文档里取的。

二、安装与第一次启动

# 首选
brew install herdr
# 或官方脚本
curl -fsSL https://herdr.dev/install.sh | sh
# 或 mise
mise use -g herdr

Windows 现在也已 GA：一行 PowerShell 装上（powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"），企业安全软件拦无文件脚本时改用 install.cmd 版本，Windows ARM64 跑 x86_64 构建（模拟）。官方维护了一份已知限制清单，不长，装前值得看一眼。补全脚本支持 bash / zsh / fish / elvish / powershell：herdr completion zsh。

升级要注意安装来源：直接安装的用 herdr update；Homebrew、mise、Nix 装的用各自的包管理器（herdr update 对它们不生效）。直接安装还能切更新通道——herdr channel set preview 跟进 master 的预发布版（可能回归），herdr channel set stable 切回，包管理器安装不支持预览通道。

装完在任意项目目录里敲：

cd ~/code/ZataTree
herdr

它启动或连接默认后台会话，不需要你去管 socket 在哪。第一次会走一个 onboarding（也可以 onboarding = false 跳过）。如果一个 workspace 都没有，它会自动开一个。

我本机的实际状态：

$ herdr --version
herdr 0.9.0

$ herdr status
client:
 version: 0.9.0
 channel: stable
 protocol: 22
 endpoint_protocol_generation: 1

server:
 status: running
 version: 0.9.0
 endpoint_compatible: yes
 private_protocol: 22
 private_protocol_compatible: yes
 socket: /Users/zata/.config/herdr/herdr.sock

update:
 restart_needed: no
 server_binary_stale: no

注意这一行：server 是 running，而 client 是我每次敲 herdr 才起的。这是理解 Herdr 的第一把钥匙——server 活着，你的活就活着。

三、概念模型：workspace / tab / pane / agent

比 tmux 多了一层"工作区"，而且这层是按项目切而不是按窗口切：

workspace — 项目级容器，对应一个仓库/一个项目。侧边栏按 workspace 分组。
tab — workspace 内的标签页。
pane — tab 内可分割的终端格子，每个格子通常跑一个 Agent。
agent — Herdr 从 pane 里检测出来的编程 Agent 进程，是关注对象而不是容器。

prefix+w 或侧边栏的 switch 面板把这三层同时摊开，是这个模型最直观的一屏——左侧边栏分 spaces / tabs / agents 三段，Agent 名字下面是它的状态：

我本机现在的样子（--json 输出是我删掉无关字段后的样子）：

$ herdr workspace list
{"result":{"workspaces":[
 {"workspace_id":"w4","label":"freshai","number":1,"pane_count":2,"tab_count":1},
 {"workspace_id":"w6","label":"zata_code_template","number":2,"pane_count":1,"tab_count":1}
],"type":"workspace_list"}}

$ herdr pane list
{"result":{"panes":[
 {"pane_id":"w4:p1","workspace_id":"w4","cwd":"/Users/zata/code/freshai",
 "terminal_title":"⠸ Complete external skill change review task in worktree","agent_status":"unknown"},
 {"pane_id":"w4:p3","workspace_id":"w4","cwd":"/Users/zata/code/ZataTree",
 "terminal_title":"⠧ 询问 herdr 相关信息","agent_status":"unknown"},
 {"pane_id":"w6:p1","workspace_id":"w6","cwd":"/Users/zata/code/zata_code_template",
 "terminal_title":"✳ Greeting and session start","agent_status":"unknown"}
],"type":"pane_list"}}

pane ID 的格式是 w4:p1——workspace 短 ID 加 pane 短 ID，稳定且可引用。所有跨 pane 的命令都用它寻址。Agent 列表现在是空的，因为我当前这几个 pane 里跑的不是被识别的 Agent（原因见第八节）。

一个实践建议：每个活跃项目给一个独立 workspace。侧边栏的 Agent 汇总只有在 workspace 边界清晰时才读得懂，否则所有项目的 Agent 混成一堆，“哪个项目在等我"又变成一个需要推理的问题。

四、核心能力一：分离而不停止

这是第一个真正让你离不开它的功能。

# 分离（客户端退出，server 和 Agent 继续跑）
prefix + q

# 回来
herdr

也可以直接关掉终端窗口——效果一样。想真正结束会话和里面的 pane：

herdr server stop

Herdr 在这一点上比 tmux 多走了一步：重启恢复。server 重启后，它会恢复保存的布局，并且对装了官方集成、上报过原生 session 引用的 Agent，尝试恢复到原来的对话（[session] resume_agents_on_restore = true，默认开）。

但这里有个必须说清楚的边界：恢复的是 Agent 的原生会话，不是原始进程。你的 shell 里跑到一半的 npm run build 不会自己接着跑，别指望这个。Herdr 官方在文档里也写得很直白。

把"恢复"拆成四个问题，答案才清楚。 进程还在吗、布局回来吗、屏幕内容回来吗、对话能续上吗——官方文档就是这么拆的，我把它那张表放在这里：

情形	进程继续跑	布局	最近屏幕内容	Agent 对话
分离再附着	是	是	是（活的终端）	是（进程从没停）
server 重启	否	是	仅在开了屏幕历史回放时	仅在装了原生会话恢复时
`herdr update`（不带 `--handoff`）	兼容的 server 继续跑	重启后回来	仅在开了屏幕历史回放时	仅在装了原生会话恢复时
`herdr update --handoff`	尽力保留	是	是（交接成功时来自活终端）	是（同上）

两个默认不启用、但值得知道的能力：

屏幕历史回放：[experimental] pane_history = true，让 server 全量重启后也能把每个 pane 最近的屏幕内容铺回去。默认关的原因很正当——pane 输出里可能有 token、密钥和敏感提示词，开了就要像对待终端历史一样对待它（内容落在会话目录的 session-history.json）。
live handoff（热交接）：升级时把活着的 pane 连同进程一起从旧 server 交到新 server，跳过"停掉再重建”。命令是 herdr update --handoff，herdr --remote workbox --handoff 也能用它换掉远端的 server。实验性、需要显式开，而且包管理器安装用不了（升级走 brew/mise/nix）。边界也要说清楚：交接那一刻，在途的 CLI 请求、agent wait、事件订阅都会断，客户端要自己重连重试。

顺带一提命名会话，多环境隔离时很有用：

herdr --session work # 用或建一个命名会话
herdr session list # 列出
herdr session attach work # 附着
herdr session stop work # 停掉

socket 落在 ~/.config/herdr/sessions/<name>/herdr.sock，默认会话则是 ~/.config/herdr/herdr.sock。

五、核心能力二：状态可见——`working` / `blocked` / `done` / `idle`

Herdr 最有价值的一点是把 Agent 的状态变成了有语义的东西，而不是让你去读屏幕。

每个 pane 有一个状态，四种取值：

状态	含义	你该做什么
`working`	Agent 正在干活	别打扰
`blocked`	卡住了，等你输入/批准	切过去处理
`done`	这一轮任务完成	验收
`idle`	空着，等新指令	可以派活
`unknown`	没有检测到/上报状态	需要装集成，见第八节

侧边栏把所有 workspace 的 Agent 汇总成一个列表，默认按 workspace 分组（ui.agent_panel_sort = "spaces"），也可以切成 priority——按"谁在等我"排队的注意力队列。我认为 priority 在 Agent 多了之后更实用：它本质是一个待办队列。

状态还会沿层级向上汇总：一个 blocked 的 Agent 会让它所在的 pane、tab、workspace 都显示成 blocked；working 会让 workspace 显示活跃；done 会一直挂着，直到你真的看过它。所以侧边栏能当"哪个项目在等我"的单一入口——不是靠人记住，而是靠这条汇总规则替你维护。

状态指示符默认是彩色圆点，可以换成形状区分：

[ui]
status_indicators = "symbols" # 用不同字形区分 blocked/working/done/idle/unknown

下面这张是同一个 Agent 在 working 状态下的实拍——标题栏的 tab 1/1、顶部的工作区名 nav-keybinds、底部的 Working... 都是 Herdr 自己画的：

再加上通知：

[ui.toast]
delivery = "herdr" # herdr(应用内) | terminal(外层终端，SSH 场景好用) | system(系统通知) | off
delay_seconds = 1

[ui.toast.herdr]
position = "bottom-right"

[ui.sound]
enabled = true
# done_path = "sounds/done.mp3" # 任务完成音
# request_path = "sounds/request.mp3" # 需要你介入的音

阻塞和完成用不同的声音，这是我配完之后最满意的一条改动——不用看屏幕，光靠耳朵就知道是"干完了"还是"卡住了要我批准"。macOS 上 delivery = "system" 会先试 terminal-notifier，没有则退回 osascript（注意会显示成 Script Editor，且无法激活终端）；要 brew install terminal-notifier 才有完整体验。

Herdr 会抑制当前活跃 tab 的弹窗——你正盯着那个 pane 看，它不会弹一个框告诉你它 blocked 了。这个细节做对了。

六、用法：鼠标是默认，键盘是可选

Herdr 的入门门槛比 tmux 低，核心原因是它把鼠标做成了默认路径，前缀键只是另一条路。

鼠标：

点击 pane / tab / workspace / agent 行 → 聚焦
拖动分割边框 → 调整大小
右键 → 上下文菜单（包含分割窗格、新建标签页）
拖选文本即复制，双击一个词即复制该词——不需要 Ctrl+C
Ctrl+点击打开链接（OSC 8 超链接和可见的 http(s):// URL）。macOS 下鼠标捕获开着时要 Ctrl+点，Cmd+点需要终端原生绕过路径；也可以用 ui.mouse_capture = false 整体让出鼠标

右键的归属是可以调的。 默认右键是 Herdr 的窗格菜单，但 pane 里跑着 Claude Code、Neovim 这类开了鼠标上报的程序时，右键本来是它们的功能——Herdr 曾经统统一口吃掉，后来专门修过（issue #25）。现在这个归属是按 pane 单独选的：

右键窗格 → 菜单里的 “Send right-clicks to pane” 一键切过去；切过去之后再开菜单，这一项会变成 “Use Herdr right-click menu”，点它切回。
CLI 等价物：herdr pane input --current --right-click pane|herdr（要在目标 pane 里执行；从别处操作就换成 --pane w1:p2）。herdr pane split 也接受 --right-click pane，分割时一次定好。
socket 层是 pane.input.set，参数 right_click: "pane"。

注意它和 ui.mouse_capture = false 不是一回事：那个是把整个鼠标都让给 pane 里的应用，这个只让右键，其余交互仍归 Herdr。

不想逐个 pane 切的话，还有全局的修饰键混合模式：

[ui]
right_click_passthrough_modifier = "ctrl" # ctrl+右键转发给应用，普通右键仍开 Herdr 菜单

接受 ctrl / alt / cmd / meta / hyper，可以组合（不能带 shift）。

最后是必须提前知道的坑：右键转发出去之后，Herdr 菜单要靠右键窗格的边框唤回。不知道这一条的人，会在 pane 里反复右键、以为菜单坏了。

键盘： 前缀键默认 ctrl+b，和 tmux 一致，所以从 tmux 迁过来基本零成本。按下 ctrl+b 进入前缀模式，再按动作键。

动作	默认绑定
向右分割窗格	`prefix+v`
向下分割窗格	`prefix+minus`
新建标签页	`prefix+c`
下一个 / 上一个标签页	`prefix+n` / `prefix+p`
切到第 N 个标签页	`prefix+1..9`
重命名标签页	`prefix+shift+t`
工作区选择器	`prefix+w`
新建工作区	`prefix+shift+n`
重命名工作区	`prefix+shift+w`
方向聚焦（vim 式）	`prefix+h/j/k/l`
窗格循环切换	`prefix+tab` / `prefix+shift+tab`
关闭窗格	`prefix+x`
缩放窗格	`prefix+z`
重命名窗格	`prefix+shift+p`
侧边栏开关	`prefix+b`
分离客户端	`prefix+q`
进入复制模式（键盘复制）	`prefix+[`
查看当前全部有效绑定	`prefix+?`

复制模式。 鼠标拖选即复制之外，prefix+[ 提供一条完整的键盘路径——没有鼠标的 SSH 场景里，这是唯一的复制方式：

移动：h/j/k/l；tmux 风格的单词 w/b/e、大字词 W/B/E（按空白分词）；{/} 段落；PageUp/PageDown 翻页、ctrl+u/ctrl+d 半页。
搜索：/ 向前、? 向后，n/N 顺逆序重复。查询里没有大写字母就不区分大小写，想精确匹配就带上一个大写。
选择与复制：v 或空格开始选择（shift+v 是整行选择），y 或回车复制，q/Esc 放弃退出。Esc 会先清掉当前的选择或搜索，再按一次才退出。
复制模式不暂停进程：输出照常产生、视图跟在底部；你滚进历史时画面钉住不动。

两个容易错过的点：默认前缀就是 ctrl+b，所以在复制模式里 ctrl+b 仍然是"前缀"、不是翻页，想用它翻页得先换前缀；另外 prefix+e 能把回滚内容直接在 $EDITOR 里打开，软折行会还原成逻辑行——审一段长日志，比在终端里滚舒服得多。

给终端起个看得懂的名字。 默认窗格标题显示的是运行中程序动态设置的 terminal title——比如 Claude Code 会把它改成当前正在做的事，还带转圈动画，一直变，根本认不出哪个窗格是哪个。三级对象都能改名：prefix+shift+p（窗格）、prefix+shift+t（标签页）、prefix+shift+w（工作区），按下后弹输入框，起个名，侧边栏和窗格边框从此显示固定名字。CLI 也能改，适合脚本或远程操作：

herdr pane rename w4:p3 "zata blog" # 给指定 pane 起固定名字
herdr pane rename w4:p3 --clear # 清掉，退回动态标题

再配一条：窗格没有手动命名时，在分割边框上显示检测到的 Agent 标签：

[ui]
show_agent_labels_on_pane_borders = true

两个容易忽略但很实用的点：

prefix+? 是帮助面板，显示当前生效的绑定。 改过配置之后不用去翻文档。
字面 ctrl+b 用 prefix+ctrl+b 发送。 也就是"再按一次"。终端里有个程序真的需要收到 ctrl+b 时用这个。

配置里的绑定语法是显式的：prefix+n 表示要先按前缀，ctrl+alt+n 才是终端模式下的直接快捷键。可以直接绑普通按键（比如 n），但有风险——它会拦截你所有输入，所以除非你确实想要一个无前缀的模式，否则都用 prefix+。

[keys]
prefix = "ctrl+b"
new_tab = "prefix+c"
split_horizontal = "prefix+minus"
# 一个动作可以有多个绑定
next_tab = ["prefix+n", "ctrl+alt+]"]
# 不用进 resize 模式，直接调大小
resize_pane_right = "ctrl+shift+alt+right"

改配置改乱了的救援命令：

herdr config reset-keys # 备份 config.toml，移除自定义 [keys]，回到内置 v2 默认
herdr server reload-config # 热加载（大部分 UI 设置不用重启 pane）

七、自定义命令与弹出面板

Herdr 允许把任意命令绑到按键上，这是把日常工具接进工作流的入口：

[[keys.command]]
key = "prefix+alt+g"
type = "popup" # popup | pane | shell | plugin_action
command = "lazygit"
description = "run lazygit" # 会显示在 prefix+? 帮助面板里
width = "80%"
height = "80%"

四种类型的语义差别值得记一下：

`type`	行为
`popup`	会话级模态弹窗，不改变 tab 布局，会拿到所有输入（含 Escape）直到命令退出
`pane`	开一个临时 pane，命令退出就关掉
`shell`	后台游离执行
`plugin_action`	调用已安装插件的某个 action

popup 最实用。比如随手开一个临时 shell：

[[keys.command]]
key = "prefix+t"
type = "popup"
command = "exec \"${SHELL:-sh}\""
description = "open scratch terminal"
width = "80%"
height = "80%"

注意 popup 命令拿不到 HERDR_PANE_ID（它是会话级的，不属于任何 pane），要引用底下那个平铺 pane 得用 HERDR_ACTIVE_PANE_ID。这个坑不踩一次很难注意到。

自定义命令能拿到的环境变量里，比较有用的几个：HERDR_SOCKET_PATH、HERDR_BIN_PATH、HERDR_ACTIVE_WORKSPACE_ID、HERDR_ACTIVE_TAB_ID、HERDR_ACTIVE_PANE_ID、HERDR_ACTIVE_PANE_CWD。

标签栏右侧还能挂状态：主机名、时间、一段自定义脚本的输出。

[ui]
tab_bar_position = "bottom"
tab_bar_right = [
 { type = "zoom" },
 { type = "hostname" },
 { type = "datetime", format = "%H:%M" },
 { type = "command", command = "~/.config/herdr/status.sh", interval_seconds = 5, timeout_seconds = 2 },
]
tab_bar_right_separator = " · "

hostname / datetime / command 都在 server 端求值，所以 herdr --remote 时显示的是远端机器的值——这点很正确，看远程构建状态时不会误判。

八、关键一步：让状态真正准确——集成

如果你什么都不做，agent list 会是空的，状态全是 unknown。 我上面贴的实测输出就是这样。这不是 bug，是设计：Herdr 需要 Agent 侧有一个 hook 主动上报状态。

装法是一条命令：

herdr integration install claude
herdr integration install codex
herdr integration status

支持的一堆：pi、omp、claude、codex、copilot、devin、droid、kimi、opencode、kilo、hermes、mastracode、qodercli、qwen、cursor。

我本机 herdr integration status 的实际输出：

pi: current (v8) (/Users/zata/.pi/agent/extensions/herdr-agent-state.ts)
claude: current (v9) (/Users/zata/.claude/hooks/herdr-agent-state.sh)
codex: current (v8) (/Users/zata/.codex/herdr-agent-state.sh)
copilot: current (v3) (/Users/zata/.copilot/hooks/herdr-agent-state.sh)
kimi: current (v7) (/Users/zata/.kimi-code/hooks/herdr-agent-state.sh)
opencode: current (v11) (/Users/zata/.config/opencode/plugins/herdr-agent-state.js)
hermes: current (v5) (/Users/zata/.hermes/plugins/herdr-agent-state/__init__.py)
omp: not installed (/Users/zata/.omp/agent/extensions/herdr-omp-agent-state.ts)
devin: not installed (/Users/zata/.config/devin/herdr-agent-state.sh)
droid: not installed (/Users/zata/.factory/hooks/herdr-agent-state.sh)
qwen: not installed (/Users/zata/.qwen/hooks/herdr-agent-session.sh)
cursor: not installed (/Users/zata/.cursor/herdr-agent-state.sh)
grok: not installed (/Users/zata/.grok/hooks/herdr-agent-state.sh)
...

有意思的是：它检测到我已经装了 Claude、Codex、Copilot、Kimi、OpenCode、Hermes 的集成，但一个都没装 pi。这正是我前面 agent list 为空的原因——我当前跑在 pane 里的那些进程，不是这几个装了集成的 Agent。装完集成后必须在 Herdr 里重启那个 Agent，hook 才会生效。

集成除了报状态，还负责上报原生会话引用，这就是第 4 节"重启后恢复对话"依赖的东西。没装集成的 Agent，重启后只能恢复成一个普通 shell。

Herdr 还有一份给你自己的 Agent 看的技能文件，装上之后 Agent 就知道怎么用 herdr 控制周边窗格：

npx skills add herdrdev/herdr --skill herdr -g

或直接 herdr --skill 打印与当前二进制版本匹配的内置副本。技能文件里第一条是护栏：如果 HERDR_ENV=1 没设置，Agent 必须停下来，并说明自己没跑在 Herdr 管理的 pane 里——防止 Herdr 外部的 Agent 去控制一个不属于它的会话。

九、重头戏：把 Herdr 当 Agent 的控制平面

这才是 Herdr 和 tmux 的分水岭。所有操作都通过本地 socket 上的 JSON API，CLI 只是它的一个包装。

9.1 三层接口，按需选

层	用途
Agent 技能	教 coding agent 在 pane 内使用 Herdr
CLI 包装	脚本、简单编排、人工调试 ← 大多数情况从这层开始
原始 socket API	自定义工具、协议客户端、事件订阅

三层共用同一个控制平面。先看 CLI 的规模——这是 herdr pane --help 的命令表：

$ herdr pane --help
Commands:
 list List panes
 current Show the current pane
 get Show a pane
 layout Show pane layout information
 process-info Show pane process information
 neighbor Find a pane neighbor
 edges Show pane edge information
 focus Focus a neighboring pane
 resize Resize a pane split
 zoom Toggle or set pane zoom
 read Read pane terminal output
 rename Rename a pane
 input Set pane input routing
 split Split a pane
 swap Swap panes
 move Move a pane
 close Close a pane
 send-text Send literal text to a pane
 send-keys Send key presses to a pane
 wait-output Wait for matching pane output
 run Run a command in a pane
 report-agent Report pane agent lifecycle state
 report-agent-session Report pane agent session identity
 release-agent Release pane agent lifecycle authority
 report-metadata Report display-only pane metadata

关键点：pane 是你的手，agent 是你的眼。 用 pane run 开东西，用 pane read / agent wait 拿结果。

9.2 基础编排：起活、读输出、等结果

# 建一个工作区，指定目录和标签
herdr workspace create --cwd ~/code/project --label api

# 切一个 pane 出来跑测试
herdr pane split w1:p1 --direction right
herdr pane run w1:p2 "npm test"

# 读输出（四种来源见下）
herdr pane read w1:p2 --source recent --lines 50

# 等某个字符串出现
herdr pane wait-output w1:p2 --match "Test Suites:" --timeout 120000

pane read --source 的四种取值语义不一样，选错了会读出一堆噪声：

source	含义	适用场景
`visible`	当前渲染的屏幕	UI 反馈循环——想看用户看到什么
`recent`	带终端软折行的最近回滚	一般读取
`recent-unwrapped`	不带软折行的最近回滚	日志——不想被折行切断
`detection`	Agent 屏幕检测用的底部缓冲区快照	排查检测逻辑

我读日志一律用 recent-unwrapped。用 recent 读一段长 JSON 或宽表格，折行会把结构切碎。

9.3 Agent 之间互相指挥

这是最有意思的部分。herdr agent 提供了一组面向"别的 Agent"的动词：

$ herdr agent --help
 list List agents
 get Show an agent
 read Read agent terminal output
 send-keys Send key presses to an agent
 prompt Submit a prompt to an agent
 rename Rename an agent
 focus Focus an agent
 wait Wait until an agent reaches one of the requested states
 attach Attach directly to an agent terminal
 start Start a supported interactive agent in an existing pane
 explain Explain agent detection state

--kind 支持的 Agent 相当全：pi、claude、codex、gemini、cursor、devin、agy、cline、omp、mastracode、opencode、copilot、kimi、kiro、droid、amp、grok、hermes、kilo、qodercli、qwen、maki、muse。

于是你可以这样写一个"评审"流程——一个 Agent 等另一个 Agent 干完再接手：

# 在右窗格起一个 Codex，让它做代码审查
herdr pane split w1:p1 --direction right
herdr agent start reviewer --kind codex --pane w1:p2

# 给它派活，并直接阻塞到它需要你/干完为止
herdr agent prompt reviewer "审查 src/auth 的变更，只报问题不报风格" --wait --until blocked --timeout 600000

# 读它的结论
herdr agent read reviewer --source recent-unwrapped --lines 120

agent start 有个前置条件：目标 pane 必须停在交互式 shell 提示符上——它把 Agent 进程放进现成的 shell 里启动，并确认检测成功才算数。

看清楚 --wait --until blocked 的含义：阻塞直到那个 Agent 真的需要人类介入，而不是"命令跑完了"。这个语义差别很重要，下面 9.4 会展开。

agent prompt 的帮助里有一段很值得逐字读的行为约定：

如果目标 agent 已经处于 blocked 状态，提交会在发送任何输入之前被拒绝，返回 agent_blocked。当一个被接受的提交从非 working 状态起步时，--wait 要求在 5000ms 内观察到一个 working 或 blocked 状态，否则返回 agent_prompt_stalled。

也就是说它主动防止你往一个正在等人类输入的 Agent 里灌东西。这个栏杆方向是对的——blocked 的 Agent 需要的往往是你去回答一个问题，而不是再来一条指令。

另外几个顺手的动词：herdr agent attach reviewer 把当前终端直接接到某个 Agent 的屏幕上（不看全景，就看这一个），退出用 ctrl+b q，想给它发字面 ctrl+b 就连按两次；已经有别的直连客户端占着输入时用 --takeover 抢过来。非 Agent 的普通终端有对应的 herdr terminal attach <terminal_id>。herdr agent rename w1:p1 reviewer 改的是 Agent 的名字，改完它就是一个能用在命令里的稳定引用，比 pane ID 好记。

9.4 为什么 `agent wait` 不是"等命令跑完"

这是我觉得 Herdr 在概念上最清醒的地方。看 help 原文：

Agent waits observe semantic state, not completion of arbitrary commands.

agent wait 观察的是语义状态，不是任意命令的完成。所以在 socket 层它是这么实现的：

server 持有、事件驱动——不是客户端轮询
钉在解析出的 pane 占用者上——如果那个 Agent 被换成了另一个，“等待"不会由新来的假冒满足

配合 events.subscribe 可以做真正的编排：

{"id":"sub_1","method":"events.subscribe","params":{"subscriptions":[
 {"type":"pane.agent_status_changed","pane_id":"w1:p1","agent_status":"blocked"}
]}}

还有一个容易被忽略的竞态。如果你分两步写：

herdr agent prompt reviewer "..." # 先发
herdr agent wait reviewer --until done # 再等

两步之间 Agent 可能已经干完并进入 done，你的 wait 就漏掉了。Herdr 的解法是把 prompt 和 wait 合成一个请求——socket 层的 agent.prompt 接受内嵌的 wait 对象：

{"method":"agent.prompt","params":{
 "pane_id":"w1:p1",
 "text":"...",
 "wait":{"until":["done"],"timeout_ms":600000}
}}

一次请求原子地完成"提交 + 开始等待”，没有中间态。CLI 侧对应的就是 --wait --until。

9.5 状态上报：`report-agent` 与 `report-metadata` 的区别

任何工具（hook、插件、自定义脚本）都可以报状态，但有两个通道，语义完全不同：

命令	影响	用途
`pane report-agent`	语义状态——影响 wait、通知、汇总	告诉 Herdr “我在干活/我卡住了”
`pane report-metadata`	仅展示——只进侧边栏	显示模型名、当前子任务这类信息

# 语义：这个 pane 在干活
herdr pane report-agent w1:p1 --source my-hook --agent docs-bot --state working --message "building docs"

# 展示：只给侧边栏看的自定义字段
herdr pane report-metadata w1:p1 --source my-hook \
 --token model=opus --token summary="reviewing authentication"

别把该用 metadata 的东西丢进 report-agent。 语义状态会驱动 agent wait 的返回和通知的触发，污染它等于让整个编排逻辑读错信号。这条边界划得很清楚，值得尊重。

自定义字段在侧边栏里用 $name 引用，还能配合条件着色：

[ui.sidebar.agents]
rows = [
 ["state_icon", "agent", "$model"],
 ["$summary"],
 ["workspace", "tab"],
]
# 或者按数值变色
# [{ token = "$load", fg = "#fff", rules = [{ gt = 80, fg = "#f55", bold = true }, { gt = 50, fg = "#fc0" }] }]

侧边栏行布局本身是可编程的——rows 里放 token，最多 16 行、每行 16 个 token，支持 equals / contains / starts_with / gt / lt 做条件着色（只有第一条命中的规则生效，没有正则、没有模糊匹配、没有脚本）。还能给特定 Agent 单独换一套：

[ui.sidebar.agents.rows_by_agent]
claude = [
 ["state_icon", "agent", "state_text"],
 ["terminal_title_stripped"], # 直接把 Claude 自己的标题拿来用
 ["workspace", "tab"],
]

注意 key 必须是规范 agent ID（claude、codex、pi），claude-code 这种检测别名不接受。而且它是替换 rows 而不是追加。

9.6 插件：宿主给挂载点，你自己接行为

插件是 Herdr 留给"核心之外"的口子。官方的说法是：Herdr 保持精简的办法，是核心只管终端工作区、窗格、Agent 和一套稳定的 CLI/socket API，其余流程做成可分享的插件——一个目录、一份 herdr-plugin.toml manifest、若干宿主能启动的命令，语言随你（Bash、Node、Lua、Rust 二进制都行）。

三个定位要点：

宿主管挂载，插件管实现。 安装、manifest 校验、键位、终端窗格、事件、调用上下文、socket 访问由 Herdr 提供；实现语言、依赖、文件、持久状态由插件自己负责。
没有插件 SDK，也没有受限命令集。 整个 Herdr CLI 就是插件 API——插件里的代码想调什么就调什么。
回调写 HERDR_BIN_PATH，不要硬编码 socket。 它指向正在运行的 Herdr 二进制，顺带抹平 Unix socket 和 Windows 命名管道的差异。

v1 明确不做的事也值得先知道：不能在运行时注册 action、没有原生非终端 UI，也没有 Herdr 托管的存储 API——需要状态就自己存。

这一段是"官方文档 + 本机 0.9.0 实测"的组合：命令面、参数解析都是我跑出来的；凡是没亲手跑过的我会标出来。

（9 月 15 日二次补充：原本写着"我本机一个插件都没装"。现在装了，所以有了 9.6.7 试装实录，前面几处"没跑过"的说法已经按实测结果改掉。）

9.6.1 先看宿主给了什么

一条 --help 就能把整个插件面看完（输出截断了结尾的 AI 提示段）：

$ herdr plugin --help
Install and run workflow plugins

Usage: herdr plugin [COMMAND]

Commands:
 install Install a plugin from GitHub
 uninstall Uninstall a plugin
 link Link a local plugin
 unlink Unlink a local plugin
 enable Enable a plugin
 disable Disable a plugin
 list List installed plugins
 config-dir Print a plugin config directory
 action List or invoke plugin actions
 log Inspect plugin command logs [aliases: logs]
 pane Manage plugin-owned panes

十一个子命令分三组：装（install / link / uninstall / unlink / enable / disable / list / config-dir）、跑动作（action）、开窗格和查日志（pane / log）。

9.6.2 装：两条路径

从 GitHub 装，只接受简写，内部用 git 拉取：

herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]

交互式终端里它会先给一份信任预览——源码位置、以及将要执行的命令——你确认之后才跑 manifest 里的 [[build]]。--yes 跳过确认（脚本里用），--ref 把版本钉在某个 ref 上。

自己写的时候走 link：

herdr plugin link <path> # 插件目录，或直接的 manifest 路径
herdr plugin unlink <plugin_id>

link 不跑 build 命令，构建是你自己的事；unlink 只注销、不动文件；uninstall 会连 Herdr 管理的 GitHub checkout 一起删。反过来，已经 link 的插件不能被 install 覆盖，得先 unlink。

四个容易踩的点：

插件和启用状态是"当前用户全局"的，不属于某个会话。任何会话里装或启用，其他会话立刻可见。0.7.3 时代在命名会话里装的插件需要重新装一次。
v1 没有 plugin update，刷新 = 重新 install（会替换托管的 checkout）。
install 和 link 都会顺手把插件的 config / state 目录建好；只想拿路径就用 herdr plugin config-dir <id>。
没有 server 在跑也能装、能 link——它们只是往全局插件表里注册，不等 server。

装之前本机正好是空态，当基线很干净（装完之后长什么样见 9.6.7）：

$ herdr plugin list
No plugins installed.

$ herdr plugin list --json
{"id":"cli:plugin","result":{"plugins":[],"type":"plugin_list"}}

9.6.3 用：绑键、开窗格

装完插件不会自己冒出来。它对外提供的是 action 和窗格入口，接上手最常用的是绑键：

[[keys.command]]
key = "prefix+alt+f"
type = "plugin_action"
command = "herdr-file-viewer.open-file-viewer" # 插件id.action
description = "open file viewer"

command 写 action id：本地 id（open-file-viewer）和限定名（插件id.action）都可以，本地 id 命中多个插件时报 ambiguous_plugin_action 让你补限定名——所以一开始就写限定名最省事，herdr plugin action invoke 同理。

窗格是插件的"界面"。herdr plugin pane open 让 manifest 里声明的 [[panes]] 命令变成一个 Herdr 管理的终端窗格，摆放方式可以在命令行覆盖 manifest 的默认值：

herdr plugin pane open --plugin ID --entrypoint ID \
 --placement split --direction right [--cwd PATH] [--env KEY=VALUE]

`placement`	行为
`overlay`（manifest 默认）	临时缩放的覆盖层，盖在当前 pane 上；关闭时恢复原来的焦点和缩放
`popup`	会话级模态弹窗，不改布局，拿到全部输入（含 Esc），命令退出或收到 `popup.close` 就关
`split`	常规分割窗格
`tab`	新标签页
`zoomed`	放大窗格

popup 是最"不像 pane"的一种，边界记清楚：它没有 pane ID、不发 pane 生命周期事件、不参与布局/持久化/agent API，进程里也拿不到 HERDR_PANE_ID（想引用底下那个平铺 pane，读上下文 JSON）。--width / --height 只对它有意义：默认半屏，支持 80% 这类百分比，低于弹窗最小值会被夹紧；Settings、Copy mode 这类模态开着时开 popup 会返回 ui_busy。

踩坑：--help 不是完整真相。 0.9.0 的 herdr plugin pane open --help 里，--placement 的候选值只列了 overlay|split|tab|zoomed，--width / --height 根本没出现。但解析器是接受 popup 的：

$ herdr plugin pane open --plugin nope.nope --entrypoint nope --placement popup
{"error":{"code":"plugin_not_found","message":"plugin not found"},"id":"cli:plugin"}

$ herdr plugin pane open --plugin nope.nope --entrypoint nope --placement bogus
invalid pane placement: bogus

第一条已经走到"找不到插件"这一步，说明 popup 通过了参数校验；第二条才是不合法值。顺带一提，zoomed 还有个 fullscreen 别名。摆放这件事以文档和源码为准，别以 help 为准。

跑过的动作和日志都查得到：

herdr plugin action list [--plugin ID]
herdr plugin action invoke <action_id> [--plugin ID]
herdr plugin log list [--plugin ID] [--limit N]

9.6.4 插件进程能拿到什么

调用时 Herdr 注入的环境变量：

变量	用途
`HERDR_PLUGIN_ID` / `HERDR_PLUGIN_ROOT`	插件身份、安装（或 link）目录
`HERDR_PLUGIN_CONFIG_DIR`	用户可编辑的配置，`.env` 放这里
`HERDR_PLUGIN_STATE_DIR`	插件自己的运行时状态
`HERDR_PLUGIN_CONTEXT_JSON`	完整调用上下文：workspace / tab / 焦点 pane / worktree / agent / 选中文本 / 被点击的 URL
`HERDR_BIN_PATH` / `HERDR_SOCKET_PATH`	回调入口，优先用前者
`HERDR_PLUGIN_ACTION_ID`	被哪个 action 调起来的
`HERDR_PLUGIN_EVENT` / `HERDR_PLUGIN_EVENT_JSON`	事件钩子的事件名与完整事件体
`HERDR_PLUGIN_ENTRYPOINT_ID`	窗格命令对应哪个 entrypoint
`HERDR_PLUGIN_CLICKED_URL` / `HERDR_PLUGIN_LINK_HANDLER_ID`	链接处理器专用

一条规矩：HERDR_PLUGIN_ROOT 是源码 checkout，不要往里写凭据和状态；用户配置进 CONFIG_DIR，运行时状态进 STATE_DIR。这两个目录 Herdr 负责建（CONFIG_DIR 还会从旧位置迁移一次），但里面的内容它不校验、不同步、也不删。另外 --env KEY=VALUE 可以给启动的进程加变量，不过和 Herdr 自己的变量冲突时以 Herdr 为准。

9.6.5 写：最小骨架

目录就两样东西：

my-plugin/
 herdr-plugin.toml
 peek.sh

manifest：

id = "me.file-peek"
name = "File Peek"
version = "0.1.0"
min_herdr_version = "0.7.0"
description = "在弹窗里看一眼文件"
platforms = ["linux", "macos"]

[[actions]]
id = "peek"
title = "Peek file"
contexts = ["pane", "workspace"]
command = ["bash", "peek.sh"]

[[panes]]
id = "viewer"
title = "Peek"
placement = "popup"
width = "80%"
height = "80%"
command = ["bash", "peek.sh"]

# 除了 action 和 pane，manifest 还能声明这四类（写法示意）：
[[build]]
command = ["bash", "build.sh"]

[[startup]]
command = ["node", "dist/restore.js"]

[[events]]
on = "worktree.created"
command = ["node", "dist/on-worktree.js"]

[[link_handlers]]
id = "peek-path"
title = "Peek this file"
pattern = "^file://"
action = "peek" # 必须是同一个插件声明的 action

规则清单：

command 是 argv 数组，不走 shell。 没有 glob、管道、&&；需要 shell 语义就在命令里显式起一个 shell。
id 规则不对称： 插件 id 可以用点（me.file-peek），action / pane / link handler 的 id 不能用点。所以限定名 插件id.action 天然不会歧义。
min_herdr_version 是必填，而且真的会被强制：插件要求的版本比当前二进制新，install 和 link 都会拒绝。
platforms 可以分层： 顶层不写也能 link（给个警告），item 级的 platforms 覆盖顶层。Windows 上，build / action / event 命令会解析 npm.cmd、bun.cmd 这类 PATHEXT shim，而 pane 命令走 Herdr 常规的 Windows 启动路径，必须是合法的 Windows argv 命令。
[[build]] 只在 install 时跑（link 不跑）。如果构建过程中 manifest 被改动，安装会中止——避免"预览看到的"和"实际装上的"不是同一个东西。
[[startup]] 是一次性初始化，不是守护进程。 每个启用的插件在会话恢复后跑一次，live handoff 之后也会再跑一次；client 附着、配置热加载、插件新装或新启用都不触发。适合"把插件自己的状态恢复回去"，不适合挂常驻服务。
[[events]] 的钩子由 Herdr 端触发，事件体通过 HERDR_PLUGIN_EVENT_JSON 传进来。事件名要写当前版本支持的（未知事件名会在 link 时给出警告）。
[[link_handlers]] 匹配的是 Ctrl+点击的 URL（macOS 也是 Ctrl，因为终端鼠标上报分不出 Command），pattern 是 Rust 正则，按 manifest 顺序检查，action 必须是同一插件的 action。被点的那条 URL 在 HERDR_PLUGIN_CLICKED_URL 和上下文 JSON 里。
回调写 HERDR_BIN_PATH：

const { spawnSync } = require("node:child_process");
const herdr = process.env.HERDR_BIN_PATH ?? "herdr";
spawnSync(herdr, ["workspace", "list"], { stdio: "inherit" });

官方有一份可以直接抄的例子仓库：ogulcancelik/herdr-plugin-examples（agent-telegram-notify、github-link-preview、dev-layout-bootstrap）。注意它是"示例"，不是官方维护的插件。

9.6.6 现成的：几类值得装的

市场里已经有能直接用的东西。下面这几条我都核过 manifest 或仓库说明：

插件	干什么	备注
smarzban/herdr-file-viewer	只读文件查看器：目录树 + 内容面板，支持 diff、markdown 渲染、语法高亮，开在 split 里	只在显式动作下打开，装完要自己绑键；markdown / diff 的美化靠外部 `glow` / `delta` / `bat`，没装会退回纯文本
persiyanov/herdr-reviewr	评审侧栏：看 Agent 改出来的 diff，加行内评论回传给 Agent	macOS/Linux，要求 ≥ 0.7.5；带 `worktree.created` 钩子，可以配成自动打开
alexarthurs/herdr-sidebar	VS Code 式侧栏：文件树 + git source control，语法高亮预览和 diff	manifest 在仓库的 `plugins/herdr-sidebar/` 子目录
iurysza/termscope	把终端里已经出现的文件路径 / 链接在 split 里打开	从屏幕内容取路径，不用手输

装法就是前面那条命令，三条都跑通了（完整过程见下一节）：

herdr plugin install smarzban/herdr-file-viewer
herdr plugin action list --plugin herdr-file-viewer
herdr plugin pane open --plugin herdr-file-viewer --entrypoint file-viewer --placement split

--plugin / --entrypoint 的取值来自这个插件的 manifest（id = "herdr-file-viewer"、[[panes]] id = "file-viewer"），它的两个 Unix action 是 open-file-viewer 和 open-file-viewer-tab（另有 -windows 后缀的两个，Windows 上要绑那两个）。

想找更多，官方有一个插件市场：自动索引 GitHub 上打了 herdr-plugin topic、默认分支里有合法 manifest 的公开仓库，按热度、活跃度、最新排序——今天查这个 topic 下已经有 1161 个仓库。要留意它是未审核的索引：上榜只说明那个仓库给自己打了标签，不代表 Herdr 验过。装之前先读信任与安全那一节，扫一眼 manifest 和它要跑的命令——plugin install 的那份预览就是为这个准备的。

9.6.7 试装实录：herdr-file-viewer

表里第一个我真装了一遍。选它的理由不在星数，在形状匹配：那几条里唯一 scope 就写着"只读文件查看"的、唯一过了 1.0 的（v1.16.0），而且 min_herdr_version = "0.7.0" 是几个候选里最低的，兼容性最宽。

第一步：install，以及那份预览到底给不给你看。

$ herdr plugin install smarzban/herdr-file-viewer --yes
Plugin install preview:
 id: herdr-file-viewer
 version: 1.16.0
 source: smarzban/herdr-file-viewer
 commit: 78441da81e63d5fc416ab63fa99d006161595523
 actions: 4 startup commands: 0 events: 0
 panes: 1 link handlers: 0 build commands: 2
 build: /bin/sh scripts/fetch-or-build.sh
 build (skipped on macos): powershell -NoProfile ... fetch-or-build.ps1
 action open-file-viewer: bash scripts/open-file-viewer.sh
 action open-file-viewer-tab: bash scripts/open-file-viewer-tab.sh
 action open-file-viewer-windows: powershell -NoProfile ... open-file-viewer.ps1
 action open-file-viewer-tab-windows: powershell -NoProfile ... open-file-viewer-tab.ps1
 pane file-viewer: ./target/release/herdr-file-viewer
Installed herdr-file-viewer from smarzban/herdr-file-viewer.
Config: /Users/zata/.config/herdr/plugins/config/herdr-file-viewer

预览是真东西，不是装饰：它把 install 将要执行的每一条 [[build]]、每一个 action 的实际 argv 全列出来，连那两条上千字符的 Windows PowerShell 单行也原样摊开，还标出哪些被当前平台跳过（build (skipped on macos)）。要审计第三方插件，这一屏就是审计面。

一个约束值得单独说：源码里有一条 remote plugin install requires --yes when stdin is not interactive（我没实跑，一开始就带了 --yes）。结论是脚本、CI、Agent 里装插件必然带 --yes，也就是必然跳过人工确认。所以更稳的顺序是先不带 --yes 跑一次、人工读完预览、再决定要不要带。

第二步：[[build]] 干了什么，东西落在哪。

fetch-or-build.sh 走快路径——按 manifest 版本加平台下载预编译二进制、校验 SHA-256，失配才回退 cargo build。本机没回退，直接产出 target/release/herdr-file-viewer，file 出来是 Mach-O arm64、3.7MB。

这一步建议真的看一眼：[[panes]] 里声明的是相对路径 ./target/release/herdr-file-viewer，构建静默失败时 install 不会报错，要到你按键那一刻才发现窗格起不来。

位置	内容
`~/.config/herdr/plugins/github/herdr-file-viewer-c993314e2614/`	托管 checkout（含构建产物），`uninstall` 会连它一起删
`~/.config/herdr/plugins/config/herdr-file-viewer/`	用户可编辑配置，`herdr plugin config-dir <id>` 打印的就是这个
`~/.local/state/herdr/plugins/herdr-file-viewer/`	插件自己的运行时状态

对应 9.6.4 那条规矩：构建产物落在 PLUGIN_ROOT 里，被重新 install 覆盖是正常行为，插件不该往这儿写状态。

第三步：绑键——别照抄 README 的键，先查默认表。

README 推荐 prefix+f。我先对着 0.9.0 的默认 prefix 表核了一遍，被占用的是 shift、n、c、p、minus、v、q、l、h、z、w、j、g、alt、x、t、r、k、b，f 确实空闲。

[[keys.command]]
key = "prefix+f"
type = "plugin_action"
command = "herdr-file-viewer.open-file-viewer"
description = "open file viewer in split"

[[keys.command]]
key = "prefix+shift+f"
type = "plugin_action"
command = "herdr-file-viewer.open-file-viewer-tab"
description = "open file viewer in tab"

然后热加载，它会把诊断回给你：

$ herdr server reload-config
{"id":"cli:server:reload-config","result":{"diagnostics":[],"status":"applied","type":"config_reload"}}

diagnostics: [] 就是干净。我只验证了"正常绑定不报错"这一侧，没去构造绑错的样本，所以不把这句话当完整错误清单用。

第四步：确认它真的画出来了。

action invoke 返回成功只代表命令被派发，不代表窗格活着。两个真凭据：

$ herdr plugin log list --plugin herdr-file-viewer
... "exit_code":0, "status":"succeeded" ... "type":"plugin_pane_opened"
 "pane_id":"wB:p7", "label":"Files", "focused":true

再加一次屏幕读取（--source detection 读后台缓冲，不受你滚动的影响）：

$ herdr pane read wB:p7 --source detection --format text
┌zata_code_template─────┐┌.claude────────────────────────────────────────────────┐
│ ▸ .claude ▐││Directory: select a file to view │
│ ▸ .cursor ▐││ │
│● ▸ docs ││ │
│ ▸ src ││ │
│▄▄▄▄▄▄▄▄▄▄▄▄▄ ││ │
└fix/alembi…consistency─┘└─────────────────────────────────────────────────? help┘

两栏、git 状态标记（●）、底栏分支名都在，才算装成。

装完留下的五条经验

CLI 调 action 打在"焦点窗格"上，不是你的窗格。 我在 wC 的 pane 里执行 plugin action invoke，split 却开在了另一个工作区 wB。返回值里的 context.focused_pane_id / workspace_id 会告诉你目标是谁。人在界面上按键没这个问题，脚本里容易踩。
plugin pane 的 cwd 是插件根目录，不是工作区。 pane open 返回里 cwd 和 foreground_cwd 都是 <plugin_root>。所以插件里用相对路径当参数会指到自己家；要拿工作区路径得读 HERDR_PLUGIN_CONTEXT_JSON。
验证完要收尾，而且 close 是位置参数。 herdr plugin pane close <pane_id>，写成 --pane-id 会打 usage 纠正你。再用 pgrep -f <binary> 确认子进程真退了——窗格关掉不等于进程消失，别默认它干净。
“支持 markdown 渲染"这类话要看外部依赖。 它的美化接的是外部 glow / delta / bat，我本机三个都没有，于是走纯文本 fallback。功能没坏，但和插件表里那句期待的不完全是一回事。装之前 command -v glow 扫一眼。
回滚是干净的。 herdr plugin uninstall smarzban/herdr-file-viewer 删托管 checkout，键位是自己加进 config.toml 的两段、手删，没有残留状态要清。

顺带印证了 9.6.2 那句"v1 没有 plugin update"：herdr plugin --help 的十一个子命令里确实没有 update，刷新就是重新 install——而重新 install 会替换托管 checkout，连 target/release/ 里的构建产物一起没，所以插件自己的状态一定要放在 state 目录而不是根目录。

这一节如果只记一句话：插件不是"装了就有的功能”，而是"宿主给你挂载点、你自己把行为接上去"。 它也解释了为什么 Herdr 本体能一直保持这么瘦。

十、多机：本地和远程在同一个窗口

# 临时接一台机器
herdr --remote workbox

# 或者存下来，之后在侧边栏里按机器切
herdr machine add workbox --label "Build machine"
herdr machine list
herdr --remote-keybindings server # 远程用服务器的按键绑定，而不是本地的

“远程"有三种走法，先选对。 差别不只是习惯：

走法	谁在跑 server	适合
本机 `herdr`	本机	日常
`ssh you@server` 再跑 `herdr`	远端，纯 tmux 式	手机 SSH 客户端；你本来就活在 SSH 里
`herdr --remote workbox`	远端，UI 由本地 client 画	想要"远程会话手感像本地”

第三种和第二种有一个实际差异值得知道：先 ssh 再跑 herdr，Herdr 整个在远端运行，读不到你本地桌面的剪贴板；而 --remote 时 client 在你本机，本地截图可以直接粘到远端 pane 里（remote_image_paste 默认绑 ctrl+v，只在 --remote 下生效）。要给远端的 Agent 贴图，只有这条路走得通。

手机上盯 Agent。 Herdr 没有手机 App，也没打算做 web dashboard——装个 SSH 客户端连上跑着任务的机器，敲 herdr，同一套持久会话就在窄屏里打开了。TUI 会自适应：侧边栏收成移动版切换器，Agent 行带上 tab 上下文，切工作区、看 pane、查状态都不用离开 SSH。iPhone 上官方点名 moshi 用着顺。

设计上有两个细节做得对：

本地和远程的 Agent 汇总在同一个列表里，每台机器的连接独立重连——断了一台不会拖垮其他。
展示类设置跟随 client，运行类设置跟随 server。 主题、侧边栏布局、复制行为来自你本地 client 的配置（你 SSH 过去，看到的还是自己的主题）；pane 默认值、worktree、集成、自定义命令属于跑着 pane 的那台 server。这个切分很清晰，避免了"我改了主题怎么远程机器没变"这类困惑。

herdr --remote 默认会生成一份私有 SSH config（先 include 你的 ~/.ssh/config，再补上 ServerAliveInterval / ServerAliveCountMax 作为兜底，你自己设的 keepalive 优先），并用私有 control socket 复用第一次认证的连接。不想让它插手就 manage_ssh_config = false。

另一个不在 tmux 里的东西是 worktree：

herdr worktree list
herdr worktree create --branch feature/x --base main
herdr worktree open --branch feature/x
herdr worktree remove --workspace w7

它把 git worktree 拉成工作区的一组子行。关闭父工作区会关掉这一组，但不会删掉 checkout 目录和分支；worktree remove 会先请求安全删除，git 拒绝（有改动或未跟踪文件）时再二次确认，然后才 force。分支永远不会被删掉。 这个安全设计我认为是正确的默认。

十一、配置速查

配置文件：~/.config/herdr/config.toml（Windows 是 %APPDATA%\herdr\config.toml）。相关命令：

herdr --help # 会显示解析到的配置路径
herdr --default-config # 打印完整默认配置（带注释，是最好的文档）
herdr --default-config > ~/.config/herdr/config.toml # 全量落盘再改
herdr server reload-config # 热加载
herdr config reset-keys # 按键绑定重置

Herdr 没有配置文件也能跑；值非法会退回安全默认并在启动时告警（不静默）。

几个我认为值得一改的项：

[terminal]
shell_mode = "auto" # macOS 上 auto = 登录 shell，/usr/libexec/path_helper 和 Homebrew 的 PATH 才会生效
new_cwd = "follow" # follow(继承来源 pane) | home | current | 固定路径如 "~/Projects"

[ui]
status_indicators = "symbols" # 用形状而非仅颜色区分四种状态
agent_panel_sort = "priority" # 变成"谁在等我"的注意力队列
prompt_new_tab_name = false # 新建 tab 不弹窗问名字，省一次交互

[ui.toast]
delivery = "terminal" # SSH 场景下让外层终端发通知

[server]
headless_cols = 160 # 没有 client 连接时的虚拟终端宽度（默认 120x40）
headless_rows = 50

headless_rows/cols 这个不是小事：没有 client 连着时，server 用一个 120×40 的虚拟终端来算布局。Agent 的 TUI 渲染是按 pane 尺寸做的——尺寸变了它会重排。所以你在无 client 状态下跑的 Agent，看到的界面尺寸和你回头附上去时不完全一致。这不是 bug，但值得知道。

主题与外观。 内置 11 套主题，也可以在主题上逐个覆盖颜色 token：

[theme]
name = "catppuccin" # catppuccin / terminal / tokyo-night / dracula / nord /
 # gruvbox / one-dark / solarized / kanagawa / rose-pine / vesper
auto_switch = true # 跟随外层终端的明暗自动切换
dark_name = "catppuccin"
light_name = "catppuccin-latte"

[theme.custom] # 在选中的主题上覆盖单个颜色 token
sidebar_bg = "#181825"
selection_bg = "#313244"
accent = "#f5c2e7"

theme.custom 的值可以是 hex、颜色名或 rgb(r,g,b)，也能给某个面设 panel_bg = "reset" 交还给外层终端；开了 auto_switch 之后还能用 [theme.custom.light] / [theme.custom.dark] 给明暗两态各自叠一层。

中文输入法的三个开关。 都在 [experimental] 里、默认关，但每个都值得中文用户试一次：

[experimental]
# 按 prefix 时临时把系统输入源切成 ASCII，退出后恢复——中文输入法开着也能触发 prefix 命令
switch_ascii_input_source_in_prefix = true

# Claude Code / pi / codex 这类 TUI 自己画光标，macOS 输入法会把候选框跟丢；
# 把 pane 光标暴露给外层终端，输入法就能继续跟随
reveal_hidden_cursor_for_cjk_ime = true
# 只对检测到的这些 Agent 生效；留空则对所有聚焦 pane 生效
cjk_ime_agents = ["claude", "codex"]

代价和边界也说清楚：第一个是 best-effort、只覆盖 macOS 和 Windows，而且 Windows 上目前只处理韩文 IME（中文输入法不受益），macOS 上是临时切 ASCII 键盘布局、可用；第二个会让那些"隐藏光标又不用别的东西代替"的应用多出一个可见光标（比如 vim 的普通模式），介意的话就把 cjk_ime_agents 列成常用 Agent，让它只在这些 pane 里生效。

几个散点：

[terminal] kitty_graphics（默认开）：外层终端支持 Kitty 图形协议时，pane 里的图片会真正渲染出来。
索引绑定：switch_tab = "prefix+1..9"（默认）、switch_workspace = "prefix+shift+1..9"、focus_agent = "prefix+alt+1..9"——一行配置换来"按序号直达"；旧的 [keys.indexed] 仍在解析，但新配置用这三个。
[advanced] scrollback_limit_bytes：每个 pane 的回滚上限，默认 10MB（对齐 Ghostty）。

环境变量一览：

变量	用途
`HERDR_CONFIG_PATH`	覆盖配置文件路径
`HERDR_SESSION`	为 CLI 命令选择命名会话
`HERDR_SOCKET_PATH`	覆盖 socket 路径
`HERDR_ENV`	在 Herdr 管理的 pane 进程内设为 `1`（技能文件的护栏靠它判断）
`HERDR_PANE_ID` / `HERDR_TAB_ID` / `HERDR_WORKSPACE_ID`	当前 pane 的标识
`HERDR_LOG`	日志过滤，如 `HERDR_LOG=herdr=debug`
`HERDR_DISABLE_SOUND`	关掉声音

排障时日志在这三个文件：~/.config/herdr/herdr.log、herdr-client.log、herdr-server.log。提问时记得连轮转后的兄弟文件一起带上。

十二、避坑清单

#	坑	现象	正确做法
1	不装集成就指望状态准确	`agent list` 为空，全 `unknown`	`herdr integration install <name>`，然后在 Herdr 内重启该 Agent
2	以为重启能恢复进程	shell 里跑到一半的命令没了	只有装了集成并上报过 session 引用的 Agent 能恢复对话，进程不恢复
3	`popup` 命令里读 `HERDR_PANE_ID`	拿到空值，脚本行为异常	popup 是会话级，用 `HERDR_ACTIVE_PANE_ID`
4	分两步 prompt + wait	Agent 干太快，`wait` 漏掉已完成状态	用 `--wait --until`，或 socket 层的 `agent.prompt` + 内嵌 `wait`（原子）
5	拿 `report-agent` 报展示信息	通知和 wait 被错误状态触发，编排读错信号	展示信息走 `report-metadata`，语义状态才走 `report-agent`
6	读日志用 `recent`	长行被软折行切断，结构破碎	读日志用 `recent-unwrapped`；看用户所见用 `visible`
7	绑定普通按键没留意	输入的字符被 Herdr 拦截	一律用 `prefix+`，除非明确要一个无前缀模式
8	改完配置不热加载	改了半天没生效	`herdr server reload-config`；按键乱掉用 `herdr config reset-keys`
9	忘了无 client 时的尺寸	Agent TUI 在附着前后布局不一致	用 `[server] headless_cols/rows` 定成你常用的尺寸
10	`rows_by_agent` 用检测别名	配置不生效	key 必须是规范 ID（`claude`），不能用 `claude-code`
11	以为关工作区会删 worktree	担心丢代码	关父工作区只关 group，不删目录、不删分支；`worktree remove` 有二次确认
12	从 Herdr 里再启一个 Herdr	起不来	`[experimental] allow_nested = false` 是默认，确实需要才开
13	`herdr update` 以为会立即生效	更新了但行为没变	看 `herdr status` 里的 `restart_needed` / `server_binary_stale`
14	右键开不出 Herdr 菜单	该 pane 开了右键转发	右键窗格边框唤回菜单；或右键菜单里切回 “Use Herdr right-click menu”
15	对 brew / mise / Nix 安装跑 `herdr update`	不生效或被拒	用各自的包管理器升级；只有直接安装能用 `herdr update` 和预览通道
16	以为 server 重启后屏幕内容还在	恢复出的是空白新 shell	屏幕回放要开 `[experimental] pane_history = true`，且其中内容按终端历史对待（可能有敏感输出）
17	中文输入法开着时 prefix 按键失灵	prefix 命令不触发	`switch_ascii_input_source_in_prefix = true`（macOS 可用；Windows 目前只处理韩文 IME）
18	装完插件等它自己出现	什么都没发生	插件只声明 action 和窗格入口，要自己绑 `[[keys.command]] type = "plugin_action"`
19	以为插件只属于某个会话	别的窗口里也看到了	插件与启用状态是当前用户全局的；v1 也没有 `plugin update`，刷新靠重装
20	拿 `plugin pane open --help` 当选型依据	以为开不了 popup	0.9.0 的 help 少列了 `popup` 和 `--width` / `--height`，以文档和源码为准

十三、它适合谁

我觉得下面这几类人会立刻感觉到收益：

多 Agent 并行的人：侧边栏统一状态 + blocked 优先队列，直接替掉了"挨个窗口看一眼"这个动作
经常 SSH 到别的机器跑长任务的人：--remote + 已保存机器，本地和远程混在一个视图里；临时想看一眼进度，手机装个 SSH 客户端就能盯同一批 Agent
在搭多 Agent 编排的人：这是 Herdr 真正的差异点——agent.prompt --wait 和 events.subscribe 让你可以用语义状态而不是输出字符串匹配来调度 Agent。绝大多数同类工具只做到"起了个 pane"
不想学新键位的人：鼠标能完成一切，前缀键是 ctrl+b，tmux 用户可以无痛切换

反过来说，如果你只是单窗口单 Agent 偶尔用一下，Herdr 的价值会被大幅摊薄——它解决的问题主要来自"数量"。

也必须承认，它几乎没有全新概念：window 换成 workspace、tmux 式的状态栏、轮询换成事件订阅，每一项都能在别处找到。它的价值在组合——把这些拼成一个"以 Agent 为一等公民"的工作区，而且做得相当克制（Rust 单二进制、无 Electron、不做静默自动更新）。

如果只能记一件事：Herdr 的重点不是"同时开好几个 Agent"，而是让 Agent 的状态变成可被程序读取、可被别的 Agent 等待的信号。 想明白这一点，agent wait 和 report-agent 那一堆 API 的用法就都顺了。

参考

herdr.dev —— 官网与文档（有中文）
github.com/herdrdev/herdr —— 源码（Apache-2.0，Rust）
快速开始 / 配置 / CLI 参考
会话状态与恢复 —— 从活持久到热交接的五种恢复路径
怎么用：本地、SSH、手机 —— 三种远程姿势怎么选
Socket API —— 编程控制与事件订阅
Agent 技能文件 —— 给 Agent 看的用法说明
插件市场 —— GitHub 上 herdr-plugin 仓库的自动索引（未审核）
插件作者文档 —— manifest、命令、环境变量与信任模型的权威参考
agent-guide.md —— 让 Agent 帮你装/排查 Herdr 的提示词指南

图片来源：文中截图取自 herdr 官方文档与 GitHub README 的演示素材（herdr.dev/zh-cn/docs/how-to-work 与 README 中的演示视频，手机截图来自前者），项目以 Apache-2.0 授权。截图中的仓库名、分支名、模型名为官方演示环境内容。

CC Switch 详解：一个应用管住八个 AI 编程 CLI

Tue, 15 Sep 2026 09:30:00 +0800

整理开发机时发现一件小事：brew list --cask --versions cc-switch 报的版本是 3.14.1，但打开 CC Switch 的界面，关于页写的是 3.20.0。不是装错了——这个 cask 带 auto_updates 标记，应用自己会联网更新，Homebrew 的账本追不上它。

一个配置管理工具，几个月里自己跑出去六个小版本。这个更新频率本身就是信号：它要追的那群 AI 编程 CLI，配置面正在快速膨胀。

这篇文章把 CC Switch 讲清楚——它解决什么问题、切换时内部到底改了什么、六大功能模块各自能做到什么程度、装和升级要注意什么，以及最容易被忽略的两块风险。先说结论：它本质上不是一个「供应商切换器」，而是给八个 AI 编程工具做的一层本地配置管理层，切换只是这层管理层里最容易被看见的那个动作。

一、它要解决的问题：配置面已经失控

现代 AI 编程很少只用一个 CLI。常见组合是 Claude Code 写主力逻辑、Codex 处理特定任务、Gemini CLI 做交叉验证，再加上 OpenCode、OpenClaw 这类各有侧重的工具。

麻烦在于，每个工具一套配置，格式还都不一样：

Claude Code 走 ~/.claude/ 下的 settings 与环境变量（ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN）；
Codex 走 ~/.codex/config.toml 加 auth.json；
其他工具各有自己的 JSON、TOML 或 .env。

切换一个 API 供应商，意味着要按各家的格式分别手改一遍：改 base URL、换 token、别把别的不相关字段写坏。用几个工具就要重复几遍，漏改一个，那个工具就会继续拿着旧地址和旧 key 请求——而且往往不是立刻报错，是在你以为一切正常的时候返回一堆看不懂的失败。

MCP 服务器和 Skills 更麻烦。同一份 MCP 配置要在多个应用里各维护一份；提示词文件更是分裂成 CLAUDE.md、AGENTS.md、GEMINI.md 三个名字，内容基本一样，改一处就要记得同步另外两处。

CC Switch 就是冲着这一层来的。需要先划清边界：它管的是「配置怎么存、怎么切、怎么同步」，不负责判断某个供应商好不好。 本文同样不评价任何具体供应商的质量，只讨论管理这件事本身。

二、CC Switch 是什么

一句话：一个开源的跨平台桌面应用，把上述所有工具的供应商配置、MCP、Skills、用量和会话收拢到一个界面里管理。

项目	情况
仓库	GitHub `farion1231/cc-switch`，MIT 协议，官网 ccswitch.io
技术栈	Tauri 2 + Rust 后端，React 18 + TypeScript 前端
体量	创建于 2025 年 8 月，截至 2026-09-15 约 13.2 万 star、9,100 fork
平台	Windows 10+ / macOS 12+ / Ubuntu 22.04+、Debian 11+、Fedora 34+
支持工具	Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes

▲ 主界面顶部按应用分标签页（Claude / Codex / Gemini…），每个供应商一张卡片；当前激活的那张会显示用量与余额。图：CC Switch 官方仓库

八个工具的配置，被抽象成同一套「供应商」模型：一张卡片 = 一组配置 = 一个可以一键启用的状态。这就是它全部设计的地基，后面所有功能都建立在这一点上。

三、切换的时候，内部到底改了什么

理解 CC Switch 的关键，是搞清楚它的数据存在哪、切换时动了什么。

数据分两层存。可同步的数据——供应商、MCP、提示词、技能——进 SQLite（~/.cc-switch/cc-switch.db），它被当作单一事实源（SSOT）；只跟这台设备有关的偏好设置进 ~/.cc-switch/settings.json。分开的好处很直接：把数据库同步到多台机器，不会把 A 机器的窗口位置和 B 机器的主题设置搅在一起。

切换是双向同步，不是单向覆盖。 启用某个供应商时，它把配置写进对应 CLI 的 live 配置文件；反过来，当你编辑当前正在生效的那个供应商时，它会先从 live 文件把数据回填回来。这条设计解决的是一个很实际的场景：你在 CLI 里手动调过某个参数，如果不回填，下次切换就会把你的手改抹掉。

写入用「临时文件 + 重命名」的原子操作，避免写到一半崩溃留下半截 JSON 把工具搞挂。同时有自动备份机制，~/.cc-switch/backups/ 轮换保留最近 10 份，Skills 相关另有一份保留 20 份。

设计原则是「最小侵入」：任何时刻至少保留一个激活中的供应商，所以你没法把配置删空；反过来，就算直接卸载 CC Switch，已经写进各工具的配置仍然有效，不会让工具用不了。

有一个细节值得单独说：生效方式不统一。大多数工具需要重启终端或 CLI 才能读到新配置，只有 Claude Code 支持热切换，改完即生效。所以「我切了怎么没反应」这类困惑，多数时候答案就是重启终端。

▲ 添加供应商时，预设列表覆盖了主流模型厂商与社区中转服务，选中后通常只需填 API Key，请求地址已预设好。图：CC Switch 官方仓库

还有个容易踩的坑值得提前知道：切换供应商后，你在某个工具里装的插件配置可能「不见了」。原因是插件配置往往写在同一个配置文件里，切换时没被带过去。官方的解法是「通用配置片段」——在编辑供应商的面板里点「从当前供应商提取」，把 Key 和请求地址之外的通用数据抽出来存成片段；之后新建供应商时勾选「应用通用配置」（默认勾选），这些数据就会被一并写入。你首次导入的那份默认供应商也会完整保留所有配置项。

四、功能地图：六个模块各自做到什么程度

4.1 供应商管理

核心是预设体系：内置 50+ 预设，覆盖 AWS Bedrock、NVIDIA NIM 以及大量社区中转服务，多数预设只需填 API Key。此外支持拖拽排序、导入导出、系统托盘一键切换。

有一个值得注意的抽象叫「通用供应商」：一份配置同时同步到 Claude Code、Codex 和 Gemini CLI。如果你的诉求是「所有工具都指向同一个入口」，这比逐工具配置省事得多。

回切官方登录也是支持的：添加一个「官方登录」预设，切过去后跑一遍 Log out / Log in 流程，之后就能在官方与第三方之间来回切。Codex 还支持在多个官方账号（比如 Plus 和 Team）之间切换。

▲ 设置里的「Codex 应用增强」：开启后，使用第三方 API 期间仍可保留官方登录态，从而继续使用官方插件与手机远程操作等功能。图：CC Switch 官方仓库

4.2 本地代理与故障转移

这是整个应用里分量最重、也最需要理解成本的一块。

它会在本地起一个代理服务（默认 http://127.0.0.1:15721），支持格式转换——把一种 API 协议转成另一种，让某个工具走它本来不支持的供应商；支持自动故障转移和熔断器，某个上游挂了自动切到备用；还有供应商健康监控和整流器。

应用级接管是另一个维度：可以独立为 Claude、Codex、Gemini 或 Grok Build 配置代理，粒度细到单个供应商。也就是说，你可以只让 Codex 走本地代理，Claude Code 保持直连。

▲ 设置 → 路由：路由总开关、逐应用接管开关（图中只开了 Codex）、服务地址与实时统计。图：CC Switch 官方仓库

代价要说清楚：启用了本地代理，请求路径就多了一跳，排查问题时需要先判断是上游的问题还是本地代理的问题。好在开关是显式的，出问题可以直接关掉路由总开关回到直连。

4.3 MCP、Prompts 与 Skills 统一管理

MCP：一个面板管理 Claude、Codex、Gemini、Grok Build、OpenCode、Hermes 六个应用的 MCP 服务器，支持双向同步和 Deep Link 导入。
Prompts：带 Markdown 编辑器，能跨应用同步到 CLAUDE.md / AGENTS.md / GEMINI.md，并且有回填保护——不会把你手写的文件覆盖掉。
Skills：从 GitHub 仓库或 ZIP 一键安装，支持自定义仓库管理，同步方式可选软连接（省磁盘、实时同步）或文件复制（Windows 上更省事）。

4.4 用量与成本追踪

跨供应商追支出、请求数和 Token 用量，配趋势图表、逐条请求日志和自定义模型定价。对同时挂着多个供应商的人来说，这是把「这个月钱花哪了」变成可回答问题的功能。会话记录的扫描做了增量优化，大文件的解析速度在 3.20.1 里从秒级降到了毫秒级。

4.5 会话管理与工作区

可以浏览、搜索、恢复各工具的历史会话。OpenClaw 用户另有工作区编辑器，能直接编辑 AGENTS.md、SOUL.md 这类 Agent 文件并预览 Markdown。

4.6 系统集成

云同步：把配置目录挂到 Dropbox、OneDrive、iCloud、坚果云、NAS，或直接用 WebDAV 服务器同步，实现多机一致。
Deep Link：ccswitch:// 协议，用一条 URL 导入供应商、MCP、提示词或技能——适合团队分发统一配置。
日常项：深浅色主题、开机自启、自动更新、国际化（简中/繁中/英/日），以及一组解决首次安装登录确认、签名限制、插件同步等问题的「小工具」。

五、安装与升级

各平台路径都很常规，macOS 推荐 Homebrew：

brew install --cask cc-switch
brew upgrade --cask cc-switch # 升级

Windows 用 Releases 页的 .msi 或便携版 zip；Arch 用 paru -S cc-switch-bin；其他 Linux 发行版用 .deb / .rpm / .AppImage。macOS 包已经过 Apple 签名和公证，装完直接打开，不需要额外绕过 Gatekeeper。

回到开头那个版本号对不上的现象，它有个实际影响：别把 Homebrew 的版本号当成真实版本。因为 cask 带 auto_updates，应用会自己更新，brew list 显示的可能是几个月前的老数字。想知道当前版本，看应用界面更准。

升级路径上有一个需要留意的节点。3.20.x 这一轮里，3.20.1 带了数据库 schema 从 v17 到 v18 的迁移（升级前会自动备份，但如果要降级，必须用备份恢复）；同一版还调整了 Codex 的第三方切换机制，改成只写配置文件、不再动 auth.json，Codex 的 OAuth 账号需要重新登录一次。后面两个版本没有 schema 变更。

版本	日期	关键变化
3.20.1	08-28	适配 Codex CLI 0.149，切换改为「仅写配置」；同工作区多 ChatGPT 账号不再互相覆盖；DB schema v17→v18
3.20.2	09-07	Grok 走 xAI 原生 Responses API；恢复并行工具调用；修复提示词前缀缓存被破坏等问题
3.20.3	09-11	新增「禁用 Artifact 工具」开关；修复空 reasoning 占位符刷屏、Codex 长任务中途停止；无 schema 变更

六、边界与风险

任何工具的能力边界都值得写清楚，这个尤其。

它适合的：同时用两个以上 AI 编程 CLI、需要频繁在多个供应商之间切换、在多地多台机器上用同一套配置、或者想给团队分发统一配置的人。收益随工具数量和切换频率线性上升。

它不适合的：只用一家供应商、只用一个工具、配置写死就不动的人。这种情况下它的全部价值只剩一个可视化的配置编辑器，装它的必要不大。

风险一，也是最需要清醒对待的：预设列表不等于推荐列表。 内置的 50+ 预设里，有相当一部分是第三方 API 中转服务——这一点从 README 里占了大篇幅的赞助商区块就能直观感受到。CC Switch 的立场是中立的：它提供的是「方便地接入」这个能力，不对任何预设的模型质量、稳定性、计费透明度或合规性做背书。工具替你降低了切换成本，但没有替你承担选择成本。 用第三方中转意味着你的请求和密钥要经过第三方，这部分判断得自己做。

风险二，本地代理接管改变了请求路径。 排障时多一层变量，建议在真正依赖它之前先小范围试一次，确认故障转移的触发条件和日志能看懂。

风险三，配置文件的归属权冲突。 CC Switch 会写各工具的 live 配置文件。如果你另有脚本、dotfiles 管理工具或手工流程也在改同一份文件，两边会互相覆盖。原子写入和自动备份能防损坏，防不了逻辑冲突。

顺带一个冷知识，Linux + NVIDIA 用户可能会撞上：AppImage 默认强制走 XWayland，在较新的 Wayland + NVIDIA 环境下会出现界面点不动或缩放后黑屏。官方的逃生开关是 CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage。

七、我的判断

CC Switch 真正的价值，不在于「一键切换」这个动作节省的那几十秒，而在于它把散落在八个工具、三种格式里的配置，收敛成了一个有备份、有回滚、有单一事实源的本地管理层。

这个转变的意义在于：你开始可以回答「我现在到底在用哪套配置」这个问题了。在此之前，这个问题要靠翻四五个目录、比对若干份配置文件才能回答；现在它是一张卡片上的一行字。

值得提醒的是这个结论成立的前提：它成立，是因为你把多个工具和多个供应商当成常态来用。如果你的工作流只有一个工具加一个供应商，CC Switch 解决的是一个你并不存在的问题。工具的价值永远取决于它减掉的那部分复杂度，是不是真的存在于你的工作里。

总结

CC Switch 是给八个 AI 编程 CLI 做配置管理的开源桌面应用（Tauri 2 + Rust，MIT，13 万 star），配置管理层才是它的定位，供应商切换只是入口。
内部机制是 SQLite 单一事实源 + 设备级 JSON 双层存储、切换双向同步、原子写入、自动备份；设计上保证最小侵入，卸载不留坑。
六个功能模块里，本地代理与故障转移最重、也最需要理解成本；MCP / Prompts / Skills 的统一管理是日常使用中最省事的部分。
安装优先走 Homebrew 或官方包；升级注意 3.20.1 的数据库迁移和 Codex OAuth 需要重新登录一次；别信 brew list 的版本号，应用会自更新。
预设列表里有大量第三方中转服务，工具降低了切换成本，但没有降低判断该切到哪儿的成本——这部分始终要自己做。

它把「切换」这件事的成本压到了最低，剩下的成本，是你判断该切到哪儿的成本。

为 AI 而写的 CLI 设计指南：原则、避坑与难点

Thu, 10 Sep 2026 15:30:00 +0800

最近在给 FreshAI 写一个供 AI 操作外部能力的命令行工具，落地之后回头总结，发现它和「给人用的 CLI」几乎是两套设计哲学。传统 CLI 是给一个坐在 tty 前、能看进度、会按 y/n 的人设计的；而 Agent 看不到屏幕，它只能拿到两样东西：stdout 的字节流和进程退出码。一旦这两样东西被污染或语义不清，Agent 就会「飞盲」——重试已经成功的操作、放弃其实失败了的操作，或者把一段散文当数据去解析。

这篇文章把我踩过的坑整理成一套可复用的设计准则，骨架来自 FreshAI CLI（packages/fresh-cli，唯一依赖 httpx 的独立 Python 包），并对照 Agent CLI Guidelines、12 Factor CLI Apps、clig.dev 这些公开规范。核心心法只有一句：

把 CLI 当成一个「传输层是 argv / stdout / 退出码」的 RPC 接口，人只是其中一个调用方。

一、为什么 Agent 时代 CLI 又重要了

Agent 天生会用 CLI。 LLM 的训练语料里有大量 shell 命令，它对 git submodule add、pip install 这类「动词-名词」结构有很强的先验。相比之下，让 Agent 现学一个私有 SDK 的调用姿势，要额外喂文档、额外占上下文。
CLI 是最省 token、最可组合的能力接口。 不需要常驻进程、不需要握手协议，一个 exec 就能调用；输出可以裁剪到 Agent 真正需要的字段。
但传统 CLI 的三条默认行为，恰好都是 Agent 的天敌： ①默认交互、②进度和结果混在一起打印、③错误只给人看。

所以「为 AI 写 CLI」不是发明一套新东西，而是把 CLI 里那些给机器看的契约显式化、稳定化。

二、设计原则：到底该怎么写

2.1 默认非交互（non-interactive by default）

Agent 没有 tty，任何 input() / confirm() / 分页器都会把它卡死直到超时。FreshAI CLI 的做法是：

只有显式命令进入交互流程。 全部命令里，只有 fresh login 会打开浏览器，其余命令一律非交互。
危险操作不靠「逐次确认」保护，而靠「独立命令 + 最小权限」。 「直接公开发布」不是给草稿命令加一个 --yes，而是一条独立命令 fresh blog publish，并且在登录授权时就必须单独拿到 blogs:publish scope。这样 Agent 的「公开」意图是可审计、可拒绝的，而不是被一个交互弹窗挡住的。

这是 12 Factor CLI Apps 第 7 条（stdin 不是 tty 时也必须能跑完）在 Agent 场景下的强化版：交互是例外，不是默认。

2.2 stdout 只放结果，stderr 只放诊断

这条老规矩在 Agent 场景里是生死线。Agent 往往直接 json.loads(stdout)，你混进一行「正在上传…」，解析立刻崩。

FreshAI CLI 的分工：

通道	内容
stdout	最终结果：`--json` 时是唯一的 envelope；文本模式是正文或结果行
stderr	进度、提示、诊断、`request-id`、健康检查详情、中断消息

实现上就两个函数，所有输出都必须走它们，不允许 print() 裸奔：

def _emit_progress(message: str) -> None:
 """输出脱敏进度信息到 stderr。"""
 print(message, file=sys.stderr)

def print_json_envelope(payload: dict) -> None:
 """把 envelope 以 UTF-8 JSON 写到 stdout（单行结束，无多余日志）。"""
 json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
 sys.stdout.write("\n")
 sys.stdout.flush()

注意 flush()：Agent 常常边读边解析，缓冲没冲出去就是「命令卡住」的经典假象。

2.3 结构化输出 + 版本化 schema

成功的输出和失败的输出必须是同一个形状，这样 Agent 只需要一个解析器：

{
 "schema_version": 1,
 "ok": true,
 "result": { },
 "error": null,
 "request_id": "…"
}

失败时 ok=false, result=null，把细节放进 error：

{
 "schema_version": 1,
 "ok": false,
 "result": null,
 "error": {
 "code": "scope_denied",
 "message": "当前凭证缺少 blogs:publish 授权",
 "http_status": 403,
 "execution_status": "not_started"
 },
 "request_id": null
}

三个细节值得强调：

schema_version 是给未来留的活路。 字段只增不改不删（append-only contract），Agent 脚本就不会因为一次升级集体失灵。
error.code 是 string，不是 HTTP 状态码的复读。 invalid_input / login_required / authorization_expired / scope_denied / not_found / request_conflict / resource_state_changed / network_error / protocol_error 这些码才是 Agent 分支判断的依据。
Token-bounded。 列表命令默认分页（--limit 1-100、--offset），不要把几千行喷进 Agent 的上下文窗口——上下文是它最贵的资源。

2.4 语义化退出码，并写进文档

Agent 可以只读退出码就决定下一步，不必解析正文。FreshAI CLI 的约定：

退出码	含义
0	成功
2	本地输入 / 配置错误（未联网）
3	登录 / 授权错误
4	资源 / 冲突 / 其他 HTTP 错误
5	网络 / 超时
6	协议或凭证落盘错误
130	用户中断（128 + SIGINT）

两个坑：

argparse 出错时默认就 exit 2，正好可以复用来表达「本地输入错误」，但你要知道它是 2，别让它和你自定义的码打架。
130 是 128+SIGINT 的惯例，Ctrl+C 中断应显式返回 130，而不是 1，否则脚本无法区分「被打断」和「执行失败」。

2.5 错误要「可迁移、可恢复」，并且脱敏

好的错误信息同时服务两种读者：

给人看： message 说清楚发生了什么；
给程序看： code + http_status + execution_status 让 Agent 能自动纠错。

同时，错误输出是泄密高发区。服务端可能返回一整页 HTML、异常堆栈里可能带 token、正文可能出现在报错里。这类内容一律不能回显：

def _extract_error_message(response: httpx.Response) -> str:
 """从错误响应中提取脱敏说明；不回显服务端 HTML 或原始异常。"""
 try:
 payload = response.json()
 except ValueError:
 body_text = (response.text or "").strip()
 if body_text.startswith("<"):
 return f"HTTP {response.status_code}：服务端返回了非 JSON 响应"
 ...

跨层映射也要固定下来，Agent 才能预测：401→登录类、403→scope/授权类、404→not_found、409→冲突类、5xx/429→网络类。

2.6 幂等：所有写操作的第一公民

为什么 Agent 特别需要幂等？ 因为它会重试。超时了重试、进程被 kill 了重试、并发调度重试——人手动敲命令很少连敲两次，Agent 会。没有幂等键，就是重复发文章、重复下单、重复扣款。

FreshAI CLI 的做法：客户端生成一个 UUID 请求编号，作为 Idempotency-Key 发给服务端，并且在请求发出前就把它打到 stderr、留在错误里：

print(f"request-id: {resolved_request_id}", file=sys.stderr)
# …
extra_headers={"Idempotency-Key": idempotency_key}

服务端按 (author, request_id) + 内容摘要去重，语义必须明确写清楚：

情况	服务端行为
同编号 + 同内容 + 目标状态未变	返回原结果，`replayed=true`，不新建
同编号 + 不同内容 / 不同模式	`409 request_conflict`，不覆盖
同编号但原稿已发布 / 已删除	`409 resource_state_changed`，不复活、不自动公开

这样「重试」就变成了安全操作。反过来，如果 CLI 每次重试都生成新编号，幂等就形同虚设——这一点下面「难点」还会展开。

2.7 区分「失败」和「结果未知」

这是全篇最重要、也最容易做错的一点，值得单列一节，我放在第三部分重点讲。

2.8 配置解析要有确定的优先级

环境一多，站点/后端地址就会飘。FreshAI CLI 把解析顺序定死，并且让 doctor 命令把来源也报出来：

--server > 进程环境变量 DOMAIN > .env.local > .env > 已保存的唯一站点凭证

两条纪律：

全部缺失时，在联网前就报 invalid_input（退出码 2），绝不连接到未知站点。
绝不静默回退。 显式给了无效值就报错；本地存了多个站点就要求显式指定，不「猜」一个。

2.9 认证：让 Agent 能无人值守登录，但密钥不进 argv / history

永远不要提供 --token 参数。 命令行会进入 shell history、进程列表（ps）、CI 日志。FreshAI CLI 明确「无明文 --token 参数」。
用设备码授权（RFC 8628 风格）：CLI 创建挑战 → 用户在浏览器确认 → CLI 按 interval 轮询、领取只出现一次的 token → 原子写入本地凭证文件。
最小权限 + 有效期 + 可撤销 + 不自动续期。 scope 分开（drafts:create / drafts:read / publish），30 天到期，网页可逐台撤销。
必须给一条无头路径。 fresh login --no-browser 只打印 URL 和核对码，方便在别的设备/无 GUI 环境完成授权。

2.10 本地先校验，未联网前拒绝非法输入

能本地判定的错误，就别浪费一次网络往返，更别让它产生半成品远程状态。FreshAI CLI 在打包阶段就把这些挡掉（退出码 2）：

标题为空；--file 与 --package 同时给；
文件不是合法 UTF-8；内容全空白；
超过大小上限（Markdown ≤ 1 MiB、HTML ≤ 2 MiB、ZIP ≤ 20 MiB）；
--request-id 不是合法 UUID；--file 误传 .zip（提示改用 --package）。

2.11 命令树与命名：一致性 > 聪明

动词-名词分层，和 git 一致：fresh blog draft create / fresh blog draft get <id> / fresh blog draft list / fresh blog publish。
参数命名要全链统一。 这一条是用真实返工换来的：初版写成了 --site，与规格里的 --server 不一致，最后从参数、args、帮助文案、报错文案到测试和文档全部更名了一遍。
帮助即文档。 prog、description、每个参数的 help 都写清楚，让 Agent（通过 --help）能自学命令树。

三、重点与难点拆解

难点一：「结果未知」——网络失败不等于操作失败

现象： 一个创建文章的请求发出去，读响应时超时了。这次创建到底成功了没有？——不知道。

如果 CLI 简单地把超时当「失败」，Agent 会：

认为文章没发出去 → 重发 → 如果第一次其实成功了，就产生了重复；
或者反过来，Agent 以为成功了，实际服务端根本没收到。

正确做法：把「请求执行状态」提升为一等公民。

EXECUTION_COMPLETED = "completed" # 已知结果
EXECUTION_UNKNOWN = "unknown" # 已发出，结果未知
EXECUTION_NOT_STARTED = "not_started" # 本地拒绝，没发出

关键在区分「连接阶段失败」和「发送后失败」：

except (httpx.ConnectError, httpx.ConnectTimeout) as exc:
 # 连都没连上，请求肯定没送达
 raise TransportError("无法连接 …", sent=False, timed_out=True)
except httpx.TimeoutException as exc:
 # 发出去了但没等到响应，可能已经成功
 raise TransportError("请求超时 …", sent=True, timed_out=True)

然后对「结果未知」给出可执行的重试指令，而不是一句「失败了」：

if transport_failure.sent:
 retry_hint = (
 f"请求已发送但结果未知，请用相同命令与相同编号重试：--request-id {request_id}"
 "（不要切换 draft/publish 模式）。"
 )
 execution_status = EXECUTION_UNKNOWN

5xx 也一样处理：服务端 500 可能是写了一半，属于结果未知，不能当作确定失败。

这条原则的价值：错误分类错一档，Agent 的决策就错一个方向。区分 not_started（可安全重发）和 unknown（必须原编号重试）是「Agent 敢用这个 CLI」的前提。

难点二：幂等的边界是一个状态机

幂等键不是「查一下有没有就返回」那么简单，资源会变状态：草稿会被网页发布成公开文章、会被删除。此时同编号的旧请求该怎么答？答案是冲突，而不是复活或覆盖：

draft --(网页 publish)--> published --(不可逆)--> 公开文章
draft --(网页 delete)--> deleted --(不可恢复)

原稿还在草稿态 → 同编号同内容重放，返回原 id；
原稿已发布/已删除 → 409 resource_state_changed，不复活、不自动公开、不改动已公开文章。

同时，网页端的操作和 CLI 的创建请求可能并发，必须保证「同一状态转换只有一方成功」。这套状态机（而不是「有就返回」）才是真正可用的幂等。

难点三：凭证存储的原子性与权限

本地凭证文件里是明文 token，一旦损坏或权限过宽就是事故。要做到：

目录 0700、文件 0600，读取时校验权限，过宽直接拒绝（CredentialStoreError）；
原子写入：同目录临时文件 → fchmod → write → flush → fsync → os.replace，任何一步失败都清理临时文件、不破坏既有文件；
拒绝损坏内容，而不是静默返回空凭证（否则用户会莫名「被登出」）；
支持 FRESH_HOME 重定向，这是让测试隔离真实 ~/.fresh 的关键（下面测试部分会用到）。

descriptor, temporary_name = tempfile.mkstemp(dir=str(credentials_path.parent), …)
try:
 os.fchmod(descriptor, CREDENTIALS_FILE_MODE)
 with os.fdopen(descriptor, "w", encoding="utf-8") as fh:
 json.dump(all_credentials, fh, ensure_ascii=False, indent=2, sort_keys=True)
 fh.flush()
 os.fsync(fh.fileno())
 os.replace(temporary_name, credentials_path)
except BaseException:
 os.unlink(temporary_name) # 失败不留垃圾，也不动旧文件
 raise

难点四：超时要分层

一个 timeout 值打天下是不行的：

连接超时和读超时语义不同（前者可安全重试）；
创建/发布类请求要传文件、服务端要解包落库，只读请求则应该快速失败。FreshAI CLI 给创建类 120s 总墙钟、只读 10s；
Agent 侧还得有自己的调用超时，且要大于 CLI 超时，否则 Agent 先把 CLI 杀了，就永远拿不到 unknown 这个语义。

难点五：轮询类交互的细节

设备码登录是一条长时间、可能抖动的轮询链路，几个坑：

必须尊重服务端给的 interval，过快会被回 slow_down，要顺延并退避；
要有总截止时间（expires_in，默认 10 分钟），到点报 authorization_expired；
网络抖动不等于授权失败，应打印进度并继续轮询，而不是直接退出；
token 只发放一次，已领取再轮询要报「请重新登录」而不是重复发；
领取成功后落盘失败，要尽力撤销刚拿到的授权，否则会留下一份「用户以为没登录、服务端却存在」的僵尸凭证。

难点六：分发与版本一致性（一个真金白银的坑）

CLI 源码改了，但分发的 wheel 版本号没变（一直是 0.1.0），会发生什么？uv 看到 URL 和版本都没变，直接用缓存里的旧构建——你改了代码，用户装到的还是旧的，而且毫无报错。

规避方式：

改源码后必须重新构建并提交 wheel，让分发产物与源码一致；
从站点安装时显式强制刷新：uv tool install --reinstall --refresh "<wheel URL>"；
wheel URL 必须以真实文件名（.whl）结尾，uv 才认，所以先查元信息端点再拼 URL；
更好的做法是让版本号真正随发布递增，而不是恒定。

再往上一层是更新机制本身的设计，对 Agent 场景有两条特殊纪律：

不要做静默自动更新。 人用 CLI，更新后行为变了会自己发现；Agent 的脚本是按当次 --help/契约写的，后台悄悄换版本等于脚本脚下抽地板。正确姿势：提供 --version，可以启动时提示「有新版本」，但升级必须由调用方显式触发。
升级必须遵守 append-only contract。 旧脚本依赖的命令、参数、退出码、JSON 字段一个都不能变、不能删、不能改语义——否则每次更新都是一次全量脚本回归。schema_version 与版本提示配合，让 Agent 能感知并自行决定是否迁移。

难点七：测试策略——契约测试 + 真实入口 E2E

Agent 驱动的 CLI 出错代价高，测试要分两层：

① 契约测试（快，不发真实网络）。 用 httpx.MockTransport 注入假响应，验证 envelope 形状、错误码映射、退出码、站点解析、打包逻辑。关键是把副作用隔离掉：

@pytest.fixture(autouse=True)
def isolated_home(tmp_path, monkeypatch):
 monkeypatch.setenv("FRESH_HOME", str(tmp_path / "fresh-home")) # 别碰真实 ~/.fresh
 monkeypatch.delenv("DOMAIN", raising=False)
 monkeypatch.chdir(tmp_path)

@pytest.fixture(autouse=True)
def no_real_sleep(monkeypatch):
 monkeypatch.setattr("time.sleep", lambda seconds: None) # 跳过轮询等待

@pytest.fixture(autouse=True)
def no_real_browser(monkeypatch):
 monkeypatch.setattr(cli_auth.webbrowser, "open", lambda *a, **k: True)

② 真实入口 E2E（慢，但不可省）。 用真实浏览器走授权页、真实 CLI 子进程（从 wheel 安装、cwd 在仓库外、HOME 隔离、不传 --server 走主路径解析），验证「安装 → 登录 → 草稿 → 发布 → 撤销」的完整闭环。只测 mock 的 CLI 会在真实授权页、真实 CSP、真实跳转上翻车。

四、避坑清单（速查表）

#	坑	症状	正确做法
1	默认交互	Agent 卡在确认/分页，直到超时	默认非交互，交互只留给显式命令
2	进度写 stdout	`json.loads(stdout)` 失败	进度/日志一律 stderr
3	JSON 模式混入人类文案/彩色	解析器被 emoji、ANSI 码带偏	JSON 模式只输出一个 envelope
4	直接抛 traceback	Agent 读到一堆栈，无法纠错	结构化 `error.code` + 可执行建议
5	明文 `--token`	进 shell history / ps / CI 日志	设备码授权，token 只经本地凭证
6	把超时当失败	重复副作用（重复发文）	区分 `not_started` / `unknown`
7	忽略幂等	重试即重复写	`Idempotency-Key` + 状态机
8	静默切换站点/环境	写错环境，且无人察觉	优先级固定，缺失即报错
9	退出码随手写	脚本无法分支	语义化并写进文档，`Ctrl+C` 用 130
10	错误里带 secret/正文	泄密	错误脱敏，不回显 HTML/异常原文
11	只读命令也强制登录	`doctor` 之类无法排障	只读诊断不要求身份校验
12	凭证权限 0644	明文 token 被同机他人读取	目录 0700、文件 0600，原子写
13	跟随重定向跨 origin	串站/SSRF，写错站点	关闭自动重定向，校验同 origin
14	wheel 版本恒定	改了源码，用户装到旧构建	重建并提交 wheel，`--reinstall --refresh`
15	CLI import 后端内部代码	耦合重、装不上、版本打架	独立包，只依赖 HTTP 客户端
16	人类表格和机器输出共用一条路径	机器解析人类排版	`--json` 与文本模式分路
17	分页缺失/无上限	列表撑爆上下文	`--limit`/`--offset`，默认有界
18	只按扩展名判定内容格式	`.htm` / 无扩展名的 HTML 被静默当 Markdown 发成字面文本	内容嗅探（`<!doctype html`）兜底，或对可疑组合给出警告

五、一个最小骨架

把上面的原则压成一个可以直接抄的骨架（Python + argparse + httpx）：

# output.py —— 输出契约与退出码
SCHEMA_VERSION = 1
EXIT_OK, EXIT_LOCAL_INPUT, EXIT_AUTH = 0, 2, 3
EXIT_HTTP, EXIT_NETWORK, EXIT_PROTOCOL, EXIT_INTERRUPTED = 4, 5, 6, 130


class CliError(Exception):
 def __init__(self, code, message, *, http_status=None,
 execution_status="completed", exit_code=EXIT_HTTP, request_id=None):
 super().__init__(message)
 self.code, self.message = code, message
 self.http_status, self.execution_status = http_status, execution_status
 self.exit_code, self.request_id = exit_code, request_id


def success_envelope(result, *, request_id=None):
 return {"schema_version": SCHEMA_VERSION, "ok": True, "result": result,
 "error": None, "request_id": request_id}


def error_envelope(error: CliError):
 return {"schema_version": SCHEMA_VERSION, "ok": False, "result": None,
 "error": {"code": error.code, "message": error.message,
 "http_status": error.http_status,
 "execution_status": error.execution_status},
 "request_id": error.request_id}


# main.py —— 统一错误出口
def main(argv=None) -> int:
 args = build_parser().parse_args(argv)
 try:
 return _dispatch(args)
 except CliError as error:
 _emit_cli_error(error, as_json=bool(getattr(args, "json", False)))
 return error.exit_code
 except KeyboardInterrupt:
 print("已中断", file=sys.stderr)
 return EXIT_INTERRUPTED

配套的 _emit_cli_error / print_json_envelope 记住两条：JSON 模式走 stdout，文本模式走 stderr；进度永远 stderr。

六、交付前自检清单

默认非交互；危险操作靠「独立命令 + 最小 scope」，而不是交互确认
stdout 只有结果，stderr 只有诊断；JSON 模式不混入人类文案
统一 envelope + schema_version，成功/失败同形状
退出码语义化、已文档化，Ctrl+C 返回 130
所有写操作幂等：request-id / Idempotency-Key，并定义重放/冲突/状态变更语义
严格区分 completed / unknown / not_started，对 unknown 给出原编号重试指令
错误脱敏，不回显 token、正文、服务端 HTML、原始异常
配置优先级明确且可诊断；缺失时联网前报错；不静默回退
无明文 --token；支持无头/设备码登录；凭证 0600 原子写
本地输入校验（编码、空值、大小、互斥、格式）先于联网
列表有界（分页/limit），不撑爆上下文
契约测试用 mock transport + 隔离 HOME；E2E 走真实入口
分发产物（wheel）版本与源码一致

参考

Agent CLI Guidelines（aclig.dev） —— 面向 Agent 的十条不变量：只读默认、自描述、有界输出、注入防护、可无头认证、只增契约等
12 Factor CLI Apps（Heroku / JDX） —— 帮助、flags、stdout/stderr、错误处理、XDG
clig.dev —— 命令行界面设计通用准则
RFC 8628：OAuth 2.0 Device Authorization Grant —— 设备码授权
FreshAI CLI 源码：packages/fresh-cli/src/fresh_cli/（main.py / output.py / client.py / credentials.py / config.py / blogs.py / auth.py）

用 AI 把文章做成口播视频：三条路线、工具盘点与落地管线

Wed, 09 Sep 2026 22:09:48 +0800

总览：一条口播视频拆成四个环节

一篇现成的文章要变成口播视频，中间其实是四个环节，每个环节都有对应的 AI 方案：

环节	做什么	AI 能帮什么
稿	文章 → 口播稿	LLM 改写：口语化、加钩子、删图表依赖
音	口播稿 → 旁白	TTS 配音，或数字人口播
图	内容 → 可视画面	AI 生成图表动画、信息图、字幕
剪	素材 → 成片	素材自动匹配、自动字幕、一键成片

按投入程度，主流是三条路线，投入和质感递增：

路线	做法	适合	质感
A. 一站式图文成片	文章粘进去，自动出片	快速试水、批量产出	一般，AI 味重
B. 半自动流水线	每步用 AI，关键点人工把关	个人知识类账号（推荐）	可做到精致
C. 全代码管线	Remotion/Manim + FFmpeg，成片即代码	会写代码、要批量复用	最高，可沉淀

路线 A：一站式「图文成片」

把文章直接粘贴进工具，自动完成配音（TTS）+ 配画面 + 字幕，几分钟出一条片。

常见工具（2026-08 实测盘点）：

工具	特点
剪映「图文成片」	生态最成熟，抖音/视频号素材匹配
腾讯智影	免费，数字人，对接视频号生态
爆款兔 PopTo	数字人 + 脚本 + 分发一站式
小云雀 AI	剪映生态，主打抖音场景
蝉镜 AI	企业 IP 形象克隆
万兴播爆	跨境多语言口播

局限也明显：素材匹配比较泛（说什么都给你配城市航拍），TTS 味道重，图表类内容表现力差。适合先跑通感受下限，不适合当主力。

路线 B：半自动流水线（推荐）

大多数看起来「很精致」的知识类视频，真实做法是这条：

文章
→ AI 改写成口播稿（口语化、加钩子）
→ TTS 配音 或 自己录
→ 图表动画垫在音轨上
→ 空镜头素材穿插
→ AI 自动字幕
→ 成片

每一步都有 AI 参与，但口播稿和图表两个关键点保留人工控制。各环节的常用选择：

口播稿改写：交给 LLM（文章是「看」的，口播稿是「听」的，必须改写，见下文长度换算）；
配音：剪映内置音色（免费、够用），或更高质量 TTS；不想出镜可直接用数字人（腾讯智影、蝉镜、HeyGen）；
画面：图表动画（见「AI 图表」一节）+ 空镜头（见「B-roll」一节）交替，避免纯脸出镜；
字幕：剪映「识别字幕」一键生成，准确率已经很高。

路线 C：全代码管线

整个片子就是代码：口播稿 → TTS → Remotion/Manim 渲染图表动画 → FFmpeg 拼接 → 成片。可版本管理、可批量复用，改一个参数重新渲染全片。适合已经跑通路线 B、想规模化的人。

工具/项目	定位
Remotion	用 React 写视频，组件化、参数化批量出片
Manim	3Blue1Brown 同款数学/架构动画引擎
HyperFrames	图文转视频框架
FFmpeg	视频拼接、转码的底座工具
techscript-video-pipeline	开源的技术脚本转视频管线
video-use / OpenMontage	口播自动剪辑 / 全链路自动拼接（开源）

内容长度怎么算：文章转口播不是「念文章」

换算公式：口播语速约 240～280 字/分钟。一篇 4500 字的文章念完是 16～19 分钟——B 站/YouTube 知识区合适，抖音/视频号太长。所以多数情况要做减法：

拆系列：长文按小节拆成多期，每期一个子主题，3～5 分钟；
精华版：只保留主判断做一支 8～10 分钟，完整论述留给图文版。

文章和口播稿是两种文体，不能直接念：

文章靠结构和视觉（标题、图表、加粗），口播靠听觉（短句、重复、递进）；
ASCII 架构图、表格没法口播，要改成「嘴上说结论、画面放图」的配合；
开头 15 秒需要一个钩子（问题、反常识判断），而不是背景铺垫。

AI 图表动画的三种做法

别人视频里那些动的图表和数据动画，主流实现有三种：

1. AI 写代码渲染动画（主流，可控性最强）

让 LLM 写 Manim 或 Remotion 代码，渲染成几秒到几十秒的动画片段，插进时间线。Generative Manim 这类开源工具已经做到「一句话生成精准动画」——本质就是 AI 编程 + 动画引擎。对会代码的人，这是图表质感上限最高的做法。文章里现成的 ASCII 架构图（如 Model → Runtime → Memory/Knowledge/Skills 分层图）特别适合转成逐层浮现的动画。

2. 文生信息图工具（最快）

Napkin AI、Gamma 这类工具，把一段话自动变成信息图，导出图片或简单动画垫进视频。快，但风格受限。

3. 剪辑软件内置模板（最省事）

剪映的图表/数字滚动动画模板，改几个数字就能用，样式固定。

B-roll：素材拼接的实现原理

看起来「随便找视频拼起来」的做法，原理非常简单：口播是一条音轨，上面再叠一条「空镜头」画面轨，画面跟着内容切换。要解决的只有两件事：素材从哪来、怎么对上位置。

素材来源：

来源	说明
Pexels / Pixabay	免费可商用，按关键词下载
Storyblocks	付费素材库，量大质高
AI 生成	可灵、即梦、Runway 生成几秒定制镜头，补素材库没有的画面

自动匹配（AI 对位置）：

工具	能力
剪映「图文成片」	按台词自动配素材
阿里云智能图文匹配成片	同类能力，开放 API
Adobe Quick Cut（2026 新功能）	按指令自动剪素材和 B-roll 初稿

手工做法也不复杂：定好口播音轨后，在时间线上方叠画面轨，每个论点配一个 3～5 秒空镜；图表动画和空镜交替出现，节奏就不会闷。

落地路径：三步走

试水（1 小时）：把一篇文章粘进剪映「图文成片」跑一版，看自动生成的下限；
半自动（主力）：AI 改口播稿 → 自己录或 TTS → 图表用 AI 写 Manim/Remotion 渲染 → 剪映组装 + 空镜穿插；
管线化（跑通后）：把第二步沉淀成脚本管线（TTS + 动画渲染 + FFmpeg 拼接），以后每篇文章一键转视频。

参考

扩展式 RPA：从 Chrome 扩展原理到 Playwright 实战方案

Mon, 27 Jul 2026 10:00:00 +0800

一个观察

之前在 [[../L../Library/Python_Lib/playwright/index.md]] 里写过 Playwright 自己起隔离浏览器的常规打法。但在看到一些 RPA 工具的形态后，问题就变成另一个：

为什么有些 RPA 工具是装成 Chrome 扩展，一打开就能直接「操控」用户已经登录好的页面？

答案并不复杂：这两种工具在底层就是两套完全不同的思路。

核心原理：谁拥有那个浏览器

普通 Playwright(或者类似 Puppeteer、Selenium)启动的是全新的、独立的浏览器实例，和你日常用的 Chrome 没有任何关系。Cookies 是空的，需要重新登录或注入 storage_state。

而 Chrome 扩展型 RPA 长这样：

┌──────────────────────────────────────────┐
│ 你的 Chrome 浏览器（同进程） │
│ │
│ ┌────────────┐ ┌────────────────────┐ │
│ │ Tab: 微博 │ │ Extension: RPA 工具 │ │
│ │ (已登录) │ │ 注入 content script │ │
│ └────────────┘ └────────────────────┘ │
│ ↑ │ │
│ └────────────────┘ │
│ 共享同一个 cookie 存储 │
│ 共享同一个 origin 权限 │
└──────────────────────────────────────────┘

扩展里跑的内容脚本 (content script) 语法上是独立脚本，但它直接被注入到登录页面的 DOM 里，运行在该页面的 JS context 中。所以当它调用 fetch('/api/user/info') 时，浏览器自动带上微博的 cookies，服务器认为这就是用户本人。

整件事可以浓缩成一句话：

扩展是装在你浏览器里的代码，你在浏览器里登录了什么，它就拥有什么。

这也是为什么做需要登录态的 RPA 任务，扩展方案往往比 Playwright 简单十倍 —— 因为它根本不需要解决「登录」这个问题。

几块关键拼图

扩展形式看起来神秘，其实就是下面这几块常规 MV3 API 拼起来的：

manifest.json 声明权限：

{
 "permissions": [
 "cookies",
 "storage",
 "tabs",
 "scripting",
 "activeTab"
 ],
 "host_permissions": [
 "*://*.weibo.com/*",
 "*://*.example.com/*"
 ]
}

content.js 注入目标页面，所有 fetch 自动带登录态：

async function autoPost(content) {
 document.querySelector('#editor').value = content;
 document.querySelector('#submit').click();
}

chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
 if (msg.cmd === 'post') {
 autoPost(msg.text);
 sendResponse({ ok: true });
 }
});

后台脚本 background.js 里直接读 cookie：

chrome.cookies.getAll({ domain: '.weibo.com' }, (cookies) => {
 console.log(cookies); // 直接拿到用户的所有登录态
});

把上面三块加一个 popup.html，就是最简版「扩展式 RPA」。

两种方案对比

维度	Playwright / 独立 RPA	扩展式 RPA
启动方式	独立进程，自己的浏览器	跑在用户已有的 Chrome
登录态	无，需要自登录或注入 `storage_state`	天然继承用户浏览器的登录态
反爬检测	高（指纹、IP、行为模式）	低（就是用户本人）
用户授权	无感（代码里随便用）	需要用户主动装扩展
部署难度	简单，纯代码	需要打包扩展、上架商店或 crx 安装
资源占用	完整浏览器进程	几乎为零
适用场景	批量任务、服务器端	辅助个人用户、低频任务

反爬角度的思考

扩展式 RPA 看起来「开挂」，但也不是万能：

指纹检测：window.chrome.runtime 等扩展特征可以被检测
行为检测：点击速度、操作序列如果太机械，仍能被识别
数据回流：云端 SaaS 形态的 RPA 在网络层会被分析
扩展权限：Chrome 在安装时展示权限，敏感权限可能让用户警觉
Manifest V3 限制：MV3 收紧了远程代码执行、跨域请求，扩展型 RPA 的能力被削弱

商业产品参考

UI.Vision (Kantu)：经典老牌，扩展形式，直接读用户登录态
Browserflow：Chrome 商店里很常见
Axiom.ai：扩展 + 云端
影刀 / 八爪鱼：部分功能走扩展模式，处理需要登录的网站
Automa（开源）：GitHub 上有源码，可以学到完整的实现

用 Playwright 模拟扩展式 RPA

虽然「真扩展」的形态在 Playwright 这边不好复刻（Playwright 是独立进程，无法直接读取用户 Chrome 的 cookies），但有一种折中方案：让 Playwright 复用用户已登录的浏览器。技术上叫 Persistent Context。

核心 API 是 launch_persistent_context：

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
 # 关键：指向真实 Chrome 的用户数据目录
 # macOS : ~/Library/Application Support/Google/Chrome
 # Windows: %LOCALAPPDATA%\Google\Chrome\User Data
 context = p.chromium.launch_persistent_context(
 user_data_dir='/Users/zata/Library/Application Support/Google/Chrome',
 channel='chrome', # 强制用系统 Chrome，不是 chromium
 headless=False, # 必须可视化（见下面）
 no_viewport=True,
 args=[
 '--disable-blink-features=AutomationControlled',
 '--no-first-run',
 ],
 )
 page = context.new_page()
 page.goto('https://weibo.com')
 # 此时你已经是登录状态了，直接用
 page.locator('.follow-btn').first.click()

但这条路的坑很大

和同仓库那篇 [[../L../Library/Python_Lib/playwright/index.md]] 的警告一致 —— 复用真实 Chrome 的 Profile 风险极高：

必须先完全关闭 Chrome：用户数据目录是文件锁定的，Chrome 在开的时候 Playwright 启动会直接报 Failed to create a ProcessSingleton for your profile。
headless=False 是硬需求：不是「看得到」这么简单的诉求，而是 headless 模式下被检测概率会显著上升，自动化特征也更明显。
User Data 目录要用整个 User Data，而不是 Default。
不要做 rm -rf 这种清理动作：容易连带覆盖或损坏历史、书签。

写个辅助函数降低出错的可能：

import subprocess
import time

def kill_chrome():
 """杀进程,确保数据目录不被 Chrome 自己锁住"""
 subprocess.run(['pkill', '-9', 'Google Chrome'], check=False)
 time.sleep(2)

实际可运行的完整脚本

# rpa.py
import subprocess
import time
from pathlib import Path

from playwright.sync_api import sync_playwright


CHROME_PATH = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
USER_DATA = Path.home() / 'Library/Application Support/Google/Chrome'


def ensure_chrome_closed() -> None:
 subprocess.run(['pkill', '-9', '-f', 'Google Chrome'], check=False)
 time.sleep(2)


def run() -> None:
 ensure_chrome_closed()

 with sync_playwright() as p:
 # Playwright 启动一个临时 Chrome 进程,加载你的用户数据
 browser = p.chromium.launch_persistent_context(
 user_data_dir=str(USER_DATA),
 executable_path=CHROME_PATH,
 headless=False,
 no_viewport=True,
 args=['--disable-blink-features=AutomationControlled'],
 ignore_default_args=['--enable-automation'],
 )

 try:
 page = browser.pages[0] if browser.pages else browser.new_page()
 page.goto('https://weibo.com')

 # 验证:这里应该能直接看到登录态
 assert '登录' not in page.title(), '用户态异常,可能 Chrome 未正常启动'

 # 开始自动化...
 page.goto('https://weibo.com/u/1234567890')
 page.locator('text=关注').first.click()
 print('✅ 关注成功')

 finally:
 browser.close()
 time.sleep(1)


if __name__ == '__main__':
 run()

进阶：CDP 远程连接

launch_persistent_context 有一个尴尬的体验：用户在自己用 Chrome，你想跑 RPA，必须先杀 Chrome 再启动一次。更优雅的方案是 Chrome DevTools Protocol（CDP）远程连接：

# 第一步：用户在终端手动启动 Chrome（带远程调试）
google-chrome --remote-debugging-port=9222

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
 # 第二步：Playwright 接管这个 Chrome,而不是新启
 browser = p.chromium.connect_over_cdp('http://localhost:9222')
 context = browser.contexts[0] # 复用用户的 context
 page = context.pages[0] # 接管用户当前的 tab
 page.goto('https://weibo.com')

CDP 方案的好处：

不需要杀 Chrome
用户当前打开的 tab 可以直接被我们接管
跑完可以「无缝」还给用户

Playwright + Chrome Extension

如果目标是让用户装一个扩展，由扩展来驱动云端 Playwright，逻辑反过来：

┌─────────────────────────────────────────┐
│ 用户 Chrome │
│ ├── 你的 Extension (MV3) │
│ │ └── WebSocket 客户端 │
│ └── 普通网页 │
│ └── 被扩展的 content script 操控 │
└────────────┬────────────────────────────┘
 │ ws://localhost:8765
 ▼
┌─────────────────────────────────────────┐
│ 你的 Python 服务 │
│ ├── WebSocket Server │
│ └── Playwright(可选,云端兜底) │
└─────────────────────────────────────────┘

这种架构适合做 SaaS 化的 RPA：扩展做「采集 + 可视化」，云端 Playwright 做「批量执行」。

方案选型表

场景	推荐方案
个人脚本，偶尔跑一下	`launch_persistent_context` + 杀 Chrome
个人脚本，经常跑	CDP 远程连接 + 一个一键启动 Chrome 的 `.command` 文件
工具化，要给同事用	CDP 方案 + 配启动器
做产品，要分发	写 Chrome 扩展（完全独立，无需 Playwright）

前三种方案都没跳出 Playwright 的能力范围，基本能覆盖 90% 的需求。最后一种是真正的「扩展式 RPA」，但投入就大很多了 —— 它本身就是一个独立的产品形态，从 manifest、签名、商店审核到 MV3 限制都是另一套工程。

如果是从零开始想把 RPA 能力给到个人用户，先从 CDP 方案做起，把脚本跑通、把页面录制做成、把回放做成；等到扩展的能力真的有必要了，再考虑写 MV3 分发。

参考资料

Playwright: launch_persistent_context
Playwright: Connect over CDP
Chrome Extensions: Manifest V3 Migration
Chrome Extensions: Cookies API
rrweb / rrweb-player（会话录制的开源参考实现）
Automa - Chrome 扩展式 RPA 开源实现

浏览器会话录制与接口回放：方案调研

Mon, 27 Jul 2026 00:00:00 +0000

背景与目标

想做这样一个工具：

用户打开一个目标网站
在浏览器里手动操作（点击、输入、滚动、跳转）
后台实时记录每一步 DOM 事件 + 每个 HTTP 接口的请求/响应
操作结束后，能看到一份按时间线排列的"操作 + 接口"清单，必要时还能重放

这类能力在业内通常叫 Session Replay / 用户会话录制。

核心原理

┌─────────────┐ 事件 / 网络上报 ┌──────────┐
│ 浏览器注入 │ ────────────────────> │ 后端 │
│ SDK / 扩展 │ │ 落库 │
└─────────────┘ └──────────┘
 │ │
 │ DOM 快照 + 事件流 ▼
 └─────────────────────> 回放页面
 (rrweb-player 等)

关键三件事：

DOM 事件捕获：click / input / scroll / navigation，通常用 addEventListener 全局委托 + 事件冒泡
网络拦截：浏览器侧 XMLHttpRequest / fetch 包装一层钩子，或者用 Service Worker / 浏览器扩展的 webRequest API
DOM 变化记录：MutationObserver 监听 DOM 增量变化，配合初始快照实现像素级回放

现有方案

商业产品（开箱即用）

工具	特点
SessionStack	像素级回放 + 错误捕获 + 性能分析，企业级
FullStory	数字体验分析，强在漏斗和搜索
LogRocket	类 SessionStack，回放 + Redux/Zustand 状态回放
Hotjar	更偏热力图和漏斗
Microsoft Clarity	免费，基础回放 + 热力图

开源方案

rrweb — 最主流的开源前端录制库，用 MutationObserver + 事件监听完整还原 DOM 变化，配套有 rrweb-player 回放器。LogRocket 早期也借鉴过类似思路
rrweb-snapshot / rrweb-player — 序列化和回放子包
Playwright Trace Viewer / Patchright — 如果场景是"复现自动化流程"，Playwright 自带的 trace 就能记录每一步点击、请求、截图

自己从零做的思路

最简 MVP

浏览器扩展
 └─ content script 注入目标页面
 ├─ 监听 click / input / scroll
 ├─ 包装 XHR / fetch
 └─ 周期性上报到 /collect
后端
 └─ POST /collect → 追加写入 events.jsonl
本地 CLI
 └─ 解析 events.jsonl → 打印时间线 / 启动 rrweb-player

代码量很小，半天能跑通。

进阶版（像素级回放）

// 浏览器侧：rrweb 录制
import { record } from 'rrweb';
const events = [];
record({
 emit(event) { events.push(event); },
});
// 周期性批量上报到后端
setInterval(() => postEvents(events.splice(0)), 1000);

// 回放侧
import rrwebPlayer from 'rrweb-player';
new rrwebPlayer({
 target: document.body,
 props: { events: fetchedEvents },
});

选型建议

按"想做什么"分场景推荐：

需求	推荐方案
自己排查自动化 bug	Playwright Trace（`context.tracing.start()`），零成本
给自家产品做用户行为分析	rrweb + 自建后端，可控、私有化部署友好
想要现成的商业级方案	LogRocket / SessionStack
只想看热力图	Hotjar / Microsoft Clarity（免费）

与现有 patchright 项目的结合点

本仓库（kimi-patchright）本身在做浏览器自动化相关的 slide 调试。如果只是想在调试 slide 自动化流程时复盘浏览器里的真实操作 + 接口调用，Playwright Trace + patchright 的 page.on('request') / page.on('response') 就够用了，不需要单独再搭一套录制系统。

如果目标是 toC 的通用录制工具，那需要再想清楚定位：是要 rrweb 那种像素回放，还是只做事件流（轻量、可被搜索聚合）。

参考资料

rrweb: https://github.com/rrweb-io/rrweb
SessionStack 原理: https://www.sessionstack.com/
Playwright Trace: https://playwright.dev/docs/trace-viewer

AI 生成前端的 E2E 实践：用 Playwright 做视觉回归和功能兜底

Thu, 25 Jun 2026 14:00:00 +0800

这是「AI 时代的前端设计与实现」系列的一篇补充。前面我们聊了角色、设计系统、rules 模板和 Figma MCP；这一篇聚焦工程化落地里最常被低估的环节——端到端测试。

为什么 AI 生成的前端特别需要 E2E

AI 写前端的速度很快，但它有两个天然短板：

没有全局视角：改 A 页面时很容易把 B 页面的样式或交互带崩。
对边界状态不敏感：loading、error、empty、无权限这些状态经常被忽略。

更麻烦的是，AI 生成的代码往往看起来没问题，一跑就报错。TypeScript 和 ESLint 能拦住类型和语法错误，但拦不住这些问题：

按钮点了没反应
表单提交后没跳转
某个弹窗在特定分辨率下错位
改完配色后整个页面气质变了

E2E 测试就是针对这些问题的最后一道防线。它不只是测功能，还能帮你做视觉验收和回归防护。

E2E 要测什么

不要试图把所有东西都用 E2E 测。抓住三类高价值场景：

1. 核心用户流程（Happy Path）

用户最常用的路径必须稳定。例如电商站的「搜索 → 加购 → 结算 → 支付」。

import { test, expect } from '@playwright/test';

test('用户完成购买流程', async ({ page }) => {
 await page.goto('/products');
 await page.click('[data-testid="product-card"]:first-child');
 await page.click('[data-testid="add-to-cart"]');
 await page.click('[data-testid="checkout-button"]');
 await page.fill('[name="email"]', 'user@example.com');
 await page.click('[data-testid="submit-order"]');
 await expect(page.locator('text=订单已创建')).toBeVisible();
});

2. 错误和边界状态

AI 最容易漏的恰恰是这些：

网络失败时的 fallback UI
搜索无结果
表单校验失败
未登录访问需要权限的页面

test('搜索无结果展示空状态', async ({ page }) => {
 await page.goto('/search');
 await page.fill('[name="q"]', 'xyznotfound123');
 await page.press('[name="q"]', 'Enter');
 await expect(page.locator('[data-testid="empty-state"]')).toBeVisible();
 await expect(page.locator('text=没有找到相关结果')).toBeVisible();
});

3. 视觉回归

这是 AI 前端最关键的能力。每次 AI 改完代码，自动截图和基准图对比，像素级变化都能发现。

test('首页视觉回归', async ({ page }) => {
 await page.goto('/');
 await expect(page).toHaveScreenshot('homepage.png', {
 maxDiffPixels: 100,
 });
});

工具链选择

工具	适用场景	推荐度
Playwright	功能测试、截图回归、多浏览器、移动端模拟、trace 调试	⭐⭐⭐
Cypress	社区成熟，但多标签页、iframe 支持弱	⭐⭐
Selenium	老项目维护，新项目不推荐	⭐
Chromatic / Percy	专业 UI 回归 SaaS，适合组件级视觉对比	⭐⭐⭐
axe-core	无障碍扫描	⭐⭐⭐

建议： 新项目直接用 Playwright。它一个工具就能覆盖功能测试、视觉回归、响应式、多浏览器，失败时还能看 trace 回放。

Playwright 实战配置

安装

npm init playwright@latest

基础配置

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
 testDir: './e2e',
 fullyParallel: true,
 forbidOnly: !!process.env.CI,
 retries: process.env.CI ? 2 : 0,
 workers: process.env.CI ? 1 : undefined,
 reporter: [['html'], ['list']],
 use: {
 baseURL: 'http://localhost:3000',
 trace: 'on-first-retry',
 screenshot: 'only-on-failure',
 video: 'retain-on-failure',
 },
 projects: [
 { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
 { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
 { name: 'webkit', use: { ...devices['Desktop Safari'] } },
 {
 name: 'Mobile Chrome',
 use: { ...devices['Pixel 5'] },
 },
 {
 name: 'Mobile Safari',
 use: { ...devices['iPhone 12'] },
 },
 ],
 webServer: {
 command: 'npm run dev',
 url: 'http://localhost:3000',
 reuseExistingServer: !process.env.CI,
 },
});

关键配置解读：

trace: 'on-first-retry'：失败时保留 trace，可以逐帧回放。
screenshot: 'only-on-failure'：失败自动截图。
retries: 2：CI 里重试 2 次，排除 flaky。
webServer：自动起本地服务。

视觉回归怎么做

基础截图对比

test('登录页视觉回归', async ({ page }) => {
 await page.goto('/login');
 await page.waitForSelector('[data-testid="login-form"]');
 await expect(page).toHaveScreenshot('login-page.png', {
 maxDiffPixels: 100,
 threshold: 0.2,
 });
});

组件级视觉回归

如果你想测某个组件在不同状态下的样子：

test('按钮各状态截图', async ({ page }) => {
 await page.goto('/button-demos');

 await page.click('[data-testid="hover-trigger"]');
 await expect(page.locator('[data-testid="button-primary"]')).toHaveScreenshot('button-hover.png');

 await page.click('[data-testid="focus-trigger"]');
 await expect(page.locator('[data-testid="button-primary"]')).toHaveScreenshot('button-focus.png');

 await page.click('[data-testid="loading-trigger"]');
 await expect(page.locator('[data-testid="button-primary"]')).toHaveScreenshot('button-loading.png');
});

让视觉回归更稳定

视觉回归最怕 flaky。几个工程化技巧：

固定字体加载：截图前确保字体已加载。

await page.waitForFunction(() => document.fonts.ready);

屏蔽动态内容：时间、随机数、动画元素用 CSS 隐藏或 mock。

await page.addStyleTag({ content: '[data-testid="current-time"] { visibility: hidden !important; }' });

统一 viewport 和缩放：在 playwright.config.ts 里统一设备配置。

动画禁用：

await page.addStyleTag({ content: '*, *::before, *::after { animation-duration: 0s !important; transition-duration: 0s !important; }' });

响应式测试

AI 生成的页面常常在桌面端好看，移动端就崩。Playwright 可以很方便地多分辨率截图：

test.describe('响应式首页', () => {
 test.use({ viewport: { width: 375, height: 667 } });
 test('移动端', async ({ page }) => {
 await page.goto('/');
 await expect(page).toHaveScreenshot('homepage-mobile.png');
 });
});

test.describe('响应式首页桌面端', () => {
 test.use({ viewport: { width: 1440, height: 900 } });
 test('桌面端', async ({ page }) => {
 await page.goto('/');
 await expect(page).toHaveScreenshot('homepage-desktop.png');
 });
});

无障碍测试

AI 生成的代码容易忽略 alt、aria-label、对比度等。用 axe-core 跑一遍：

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('首页无严重无障碍问题', async ({ page }) => {
 await page.goto('/');
 const results = await new AxeBuilder({ page })
 .withTags(['wcag2a', 'wcag2aa'])
 .analyze();
 expect(results.violations).toEqual([]);
});

让 AI 参与测试工作流

E2E 不只是写测试，还可以让 AI 帮你生成和维护测试。

1. 从用户故事生成测试

把 PRD 或用户故事喂给 AI：

用户搜索商品，选择第一个结果加入购物车，进入结算页填写邮箱，提交订单后看到成功提示。

AI 输出 Playwright 测试代码，你只需微调选择器。

2. 从 Bug 报告生成回归测试

遇到一个 bug 后，先让 AI 写一个能复现它的 E2E 测试。修完 bug 再跑这个测试，确保不会回归。

3. 自动分析失败原因

Playwright 失败时会生成 trace。你可以把 trace 截图或错误日志丢给 AI，让它给出修复建议，比如：

某个选择器不稳定，建议加 data-testid
页面还没加载完，建议加 waitForSelector
某个 API 响应慢，建议 mock

4. AI 视觉验收闭环

结合 Chrome MCP / Playwright，可以建立这样的 workflow：

AI 生成代码
 ↓
Playwright 跑 E2E + 截图
 ↓
AI 对比截图 vs Figma 设计稿
 ↓
AI 提出样式修复建议
 ↓
AI 再次生成代码
 ↓
重新跑 E2E

这个闭环能大幅减少人工 Design QA 的工作量。

CI/CD 集成

在 GitHub Actions 里跑：

name: E2E Tests

on:
 pull_request:
 branches: [main]

jobs:
 e2e:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - uses: actions/setup-node@v4
 with:
 node-version: 20
 cache: 'npm'

 - run: npm ci
 - run: npx playwright install --with-deps
 - run: npx playwright test

 - name: Upload Playwright report
 if: failure()
 uses: actions/upload-artifact@v4
 with:
 name: playwright-report
 path: |
 playwright-report/
 test-results/

视觉回归基准图管理

视觉回归最怕 baseline 不同步。建议：

本地开发改 UI 时，跑 npx playwright test --update-snapshots 更新自己负责的快照。
PR 里如果改了 UI，必须在 PR 描述里说明更新了哪些截图。
CI 里不允许自动更新快照，防止 silently 通过视觉回归。

给 AI 的 Rules 建议

把 E2E 要求写进 .cursorrules 或 .cursor/rules/*.mdc：

## E2E 规范

- 新增页面或核心交互后，必须在 `e2e/specs/` 下补充对应测试
- 优先使用 Playwright 和 `data-testid` 选择器，避免依赖 CSS 类名
- 每个核心流程测试必须覆盖：正常流程、空状态、错误状态
- 视觉改动必须更新 Playwright baseline 截图
- 提交前运行 `npm run test:e2e`，确保通过
- 不要写死等待时间，优先用 `waitForSelector` / `toBeVisible` 等断言

总结

E2E 测试对 AI 生成的前端有三层价值：

功能兜底：核心流程不崩溃、边界状态有处理。
视觉验收：每次改动自动截图对比，防止 UI 漂移。
回归保险：后续 AI 迭代时，不会把已有的功能改坏。

它和 design token、组件库、TypeScript、rules 组合起来，才能把「AI 生成前端」从 demo 变成可维护、可上线的产品。

参考

从 noVNC 到 Playwright 截图流：容器内 VNC 踩坑记

Tue, 09 Jun 2026 14:00:00 +0800

背景

项目是一个 FastAPI 后端 + Playwright 驱动的浏览器自动化服务，目标是让用户在网页里远程操作一个跑在 Docker 容器内的 Chrome，完成 kimi.com 的一次性扫码/账号登录。登录态写入持久化 profile，后续 PPT 生成任务复用。

远程桌面的需求看起来很简单：

容器内：Xvfb（虚拟显示）+ openbox（窗口管理）+ x11vnc（VNC 服务端）
后端：FastAPI WebSocket 做字节中继，把前端的 RFB 流量转发到 127.0.0.1:5910
前端：@novnc/novnc 的 RFB 类连接 WebSocket，渲染桌面

架构上也很规矩：5910 不对外暴露，WebSocket 走 443/HTTPS，用管理员 token + 一次性 ticket 鉴权，没有旁路端口。

PRD 写得整整齐齐，验收清单全部打勾，看起来万无一失。然后我们就掉进了坑里。

坑一：MIT-SHM 0-byte 画面

症状：noVNC 连接成功，但画面全黑，或者显示 0-byte 的帧。

根因：x11vnc 默认使用 X11 的 MIT-SHM（共享内存扩展）加速画面抓取。在 Docker 容器里，共享内存行为跟宿主机不一致，x11vnc 读不到像素数据。

修复（2fa2602）：给 x11vnc 加参数绕过 MIT-SHM：

x11vnc -noxshm -noxkb -noxrecord -noxfixes -noxdamage ...

或者通过环境变量透传：

X11VNC_EXTRA_ARGS="-noxshm -ncache 0"

这个坑还算好填，加参数就能绕过。

坑二：Chrome VizDisplayCompositor 导致黑屏

症状：x11vnc 终于有画面了，但 Chrome 窗口区域永远是黑的。其他窗口（xterm、openbox）显示正常。

根因：Chrome 默认启用 Viz Display Compositor，把实际渲染放到独立的合成器进程里，用 GPU 或特殊缓冲区，导致普通的 X11 像素读取（XGetImage、XShmGetImage）抓不到 Chrome 内容。

修复（58cb8ed）：启动 Chrome 时禁用 VizDisplayCompositor：

google-chrome --disable-features=VizDisplayCompositor ...

这个坑比较隐蔽，因为其他应用都能正常显示，唯独 Chrome 黑屏。排查了好一阵才定位到是 Chrome 的合成器机制。

坑三：x11vnc 在 Azure VM 上的兼容性

症状：本地 Mac Docker Desktop 测试正常，推到 Azure VM（Ubuntu 24.04，内核 6.14.0-1017-azure）后，x11vnc 要么崩溃，要么帧率极低，要么随机断开。

根因：x11vnc 对内核版本、X11 扩展、共享内存的依赖比较深，不同宿主机环境表现差异很大。

这时候我们开始尝试替换 VNC 服务端。

尝试 1：x0vncserver

TigerVNC 的 x0vncserver 更轻量，但 Ubuntu 24.04 的软件源里根本没有这个包（6765172）。

尝试 2：Xtigervnc

切换到 Xtigervnc（1d3222c），但发现它的 X0 扩展支持不完整，抓取现有 X 会话的能力不如 x11vnc。

尝试 3：x11vnc + ncache

最后又滚回 x11vnc，加上 -ncache 10 做客户端缓存（8ba411d），试图缓解帧率问题。

这一系列反复说明一个问题：在容器化 + 云服务器环境下跑传统 VNC 服务端，是一件非常脆弱的事。每个环境变量、每个内核版本、每个 X11 扩展都可能成为压垮骆驼的最后一根稻草。

最终方案：彻底放弃 VNC，改用 Playwright 截图

与其继续跟 x11vnc 搏斗，我们换了一个思路：

既然 Playwright 已经开着 Chrome，为什么不直接让 Playwright 截屏？

新方案（40b9014）：

后端：Playwright 的 Page.screenshot() 每 250ms 截一张图
传输：自定义 WebSocketFrameBridge，把 PNG 字节包上 length-prefixed JSON envelope，通过现有 WebSocket 推给前端
前端：不用 noVNC RFB 了，直接用原生 WebSocket 收帧，把 PNG blob 塞进 <img> 标签
输入：前端把鼠标/键盘事件序列化成 JSON，通过同一个 WebSocket 发回后端，后端用 page.mouse.click()、page.keyboard.press() 回放

Wire 格式：

4-byte LE length (uint32)
N bytes JSON: {"type": "frame", "seq": N, "size": M, "format": "jpeg"}
4-byte LE length (uint32)
M bytes PNG payload

新旧方案对比

维度	noVNC + x11vnc	Playwright 截图流
依赖	Xvfb + openbox + x11vnc + MIT-SHM workaround	只有 Xvfb
Chrome 兼容性	需要 `--disable-features=VizDisplayCompositor`	不需要特殊 flags
容器稳定性	极易受宿主机内核/环境差异影响	纯用户态，跟宿主机无关
带宽	RFB 协议有增量压缩，带宽低	每帧完整 PNG/JPEG，带宽高
延迟	RFB 增量更新，延迟低	250ms 轮询，延迟稍高
实现复杂度	需要 RFB 中继、VNC 参数调优	自定义帧协议，前后端约 200 行
可维护性	x11vnc 是黑盒，出问题难排查	Playwright 截图是白盒，可控

牺牲了一点带宽和延迟，换来的是极高的稳定性和可维护性。

教训

VNC 协议是为局域网桌面共享设计的，强行塞进 Docker + 浏览器自动化的场景，属于削足适履。MIT-SHM、GPU 合成器、X11 扩展这些历史包袱在容器里会集中爆发。
当你在同一个组件上打了 3 个以上补丁还搞不定时，应该考虑替换它。我们在 x11vnc 上修了 MIT-SHM、VizDisplayCompositor、ncache、环境参数透传……最后发现换掉它比修好它更容易。
用你已经有的工具链解决问题。既然 Playwright 已经开着浏览器，截屏是它的一等公民 API，为什么不直接用？不要为了追求"标准方案"而引入一整套 VNC 技术栈。
“网页远程桌面"不等于"必须实现 VNC/RDP 协议”。只要用户能看到画面、能发鼠标键盘，用什么协议不重要。自定义的 JSON+PNG 帧流完全够用。

代码速查

如果你也在用 Playwright + Docker + 远程桌面，可以直接参考这个模式。

后端截屏（Python）：

async def next_frame(self) -> bytes:
 return await page.screenshot(
 type="jpeg",
 quality=70,
 full_page=False,
 )

前端渲染（TypeScript/React）：

const ws = new WebSocket(url);
ws.binaryType = "arraybuffer";
ws.onmessage = (event) => {
 const blob = new Blob([event.data], { type: "image/jpeg" });
 setFrameUrl(URL.createObjectURL(blob));
};

后端输入回放（Python）：

async def dispatch(self, event: dict) -> None:
 if event["type"] == "click":
 await page.mouse.click(event["x"], event["y"])
 elif event["type"] == "keydown":
 await page.keyboard.press(event["key"])

Playwright Chromium 在 Docker 内 SIGTRAP 启动崩溃排查实录

Mon, 08 Jun 2026 15:30:00 +0800

背景

一个 FastAPI 后端 + Playwright（驱动 Chromium 做爬虫/自动化）的项目，通过 Dokploy 部署到一台 Azure VM（内核 6.14.0-1017-azure，Ubuntu 24.04）。前端点登录按钮，后端通过 launch_persistent_context 起 Chromium 让用户走 VNC 完成一次性登录。

部署后第一次点登录就报：

TargetClosedError: BrowserType.launch_persistent_context:
Target page, context or browser has been closed
<launched> pid=191
[pid=191][err] chrome_crashpad_handler: --database is required
[pid=191][err] [191:191:...:ERROR:.../socket.cc:120] recvmsg: Connection reset by peer (104)
[pid=191] <process did exit: exitCode=null, signal=SIGTRAP>

chrome_crashpad_handler: --database is required 看起来像主角，其实只是遗书：父 chrome 进程已经 SIGTRAP，crashpad handler 被附带拉起来时没拿到参数，才吐了 usage。先理清这一点才不会被带偏。

下面把六轮被自己打脸的错误假设逐一列出，再讲真正根因。值得保留的不是答案，是思路。

假设 1：旧 profile 跨版本残留

docker-compose 把 kimi-ppt-browser-profile 命名卷挂到 /app/.courier/browser-profiles。第一反应：上次构建的 Chromium 写下的 profile 文件和这次不兼容，启动 assert。

结果：用户说"全新部署，没操作过任何东西"。卷是 fresh 的，假设不成立。

假设 2：Docker 默认 seccomp 拦 `clone3`

Chromium 1223 (Playwright ≥ 1.49 bundled) 大量用 clone3。老 Docker daemon（≤ 20.10.10）的默认 seccomp profile 直接 EPERM。

修了一行 compose：

 kimi-ppt-backend:
 security_opt:
 - seccomp=unconfined

结果：重新部署 → 同样的 SIGTRAP。排除。

假设 3：换系统 Google Chrome stable

既然 bundled chromium 1322 跑不起来，换 Google 官方 deb 装的 google-chrome-stable 总行了吧？把 Dockerfile 改成从 Google APT 装，KIMI_SLIDES_BROWSER_CHANNEL=chrome 让 Playwright 通过 channel='chrome' 调它。

结果：chrome 一样 SIGTRAP。说明不是 chromium binary 自身的 bug。

假设 4：AppArmor 拦 userns

写了一个分层探针脚本进入容器实际查原因。关键输出：

[1] docker inspect
 AppArmorProfile: docker-default
 SecurityOpt: [seccomp=unconfined]
[2] kernel sysctls
 apparmor_restrict_unprivileged_userns = 1
[4] strace of chrome stable
 chrome 主 (pid 353) sendmsg(fd4, 40 bytes) → 给 crashpad handler 发 IPC 配置
 crashpad handler (pid 355) execve(...)
 crashpad handler +++ exited with 1 +++
 chrome 主 --- SIGTRAP si_code=SI_KERNEL ← IMMEDIATE_CRASH(int3)

apparmor_restrict_unprivileged_userns=1 配合 docker-default profile 会让 chrome 创建 user namespace 失败。给 compose 加：

 kimi-ppt-backend:
 security_opt:
 - seccomp=unconfined
 - apparmor=unconfined

结果：AppArmor 是 unconfined 了，chrome 仍然 SIGTRAP。strace 显示 crashpad handler 启动后没拿到 --database= 参数就退（更详尽的 strace 揭示真正原因——见下），所以 userns 不是真正卡点。这是被自己打脸的一轮：加 apparmor=unconfined 之后我又跑了一次 strace，发现 crashpad handler 根本没走到 userns 那一步，它在解析 argv 阶段就 fail 了。

留这一段不是为了丢脸——是因为这次"加了一行还是没好"教会我：每加一行配置就重新跑一次 strace 看新输出，不能凭印象假设前一次 trace 仍然成立。

真正根因：HOME 目录不存在

回头看 [4] 那段 strace：

355 (handler) execve args = [...--initial-client-fd=5 --shared-client-connection]
 ↑ 注意：没有 --database=
355 write(stderr, "chrome_crashpad_handler: --datab...")
355 +++ exited with 1 +++

chrome 主进程传给 crashpad handler 的 argv 里没有 --database=。为什么？因为 chrome 决定 --database= 路径的算法是 ~/.config/google-chrome/Crash Reports，根据 $HOME 推。

继续探针：

[2] HOME 探测
 HOME=/home/appuser
 ls -ld /home/appuser → No such file or directory

[3] 同样的 chrome 命令用 root 跑
 <html><head></head><body></body></html> ← 正常！

Dockerfile 里有一行：

RUN groupadd -r appgroup && useradd -r -g appgroup appuser

useradd -r 创建系统用户，默认不创 home 目录。appuser 进了 /etc/passwd 但 /home/appuser 不存在。chrome 拿不到可写 $HOME → 不传 --database= 给 crashpad handler → handler exit 1 → chrome 主进程检测到 handler init 失败 → IMMEDIATE_CRASH() 调 __builtin_debugtrap() → SIGTRAP。

root 能跑是因为 HOME=/root，目录存在。

修复（一行 Dockerfile）：

RUN groupadd -r appgroup && useradd -r -g appgroup -m -d /home/appuser appuser \
 && mkdir -p /app/logs /app/downloads /app/.courier/browser-profiles \
 && chown -R appuser:appgroup /app /home/appuser

useradd -m -d /home/appuser 才会真创建 home 目录。

Dokploy Redeploy（重新 build 镜像，3-5 分钟，不是 9 秒的 hot restart）后，chrome 启动正常。

顺手修了一个 selector bug

chrome 起来后，前端点登录立刻弹"已检测到登录成功"——其实没登录。查代码发现 sites/kimi-slides.yaml:11 配的是 logged_in_selector: ".chat-input-editor"，而 kimi.com 的未登录落地页就有 .chat-input-editor，selector 立即命中，on_login_detected 被错误 fire。

从 VNC 里看登录后页面才出现的元素：

<div class="user-avatar-container" style="width: 28px; height: 28px;">
 <img class="user-avatar" src="...music_head.png" alt="登月者9246" />
 <span class="user-name">登月者9246</span>
 <div class="membership-upgrade">升级</div>
</div>

membership-upgrade（“升级"按钮）和 .user-avatar-container 都是只在登录后才出现的——是更可靠的 post-auth marker。把 selector 换成 .user-avatar-container 即可。

5 条复盘

1. `chrome_crashpad_handler: --database is required` 是结果不是原因

每次看到这一行都要立刻去找父 chrome 进程的退出信号。SIGTRAP / trap int3 几乎一定是 Chromium 内部 IMMEDIATE_CRASH()。crashpad 那段 usage 是它被附带拉起来时打出来的"遗言”，跟死因无关。

2. 剥变量比改 compose 重要

报错涉及：卷 / 权限 / seccomp / X server / GPU / 内核 / CPU 指令 / 缺库 / 容器 runtime / app config / 用户身份。每一条都可能引发同一种症状。写脚本一次性把可控变量全部剥掉（手动跑 chromium、用 /tmp 隔离卷、headless 隔离 X、--no-zygote --single-process 隔离 sandbox），比改一行 compose 重新部署等结果效率高得多。

特别有价值的一步是 strace 死前最后那个 syscall——能直接定位到 clone3 / seccomp / userfaultfd / prctl 哪一类失败。这一步把"猜容器层问题"变成"看 kernel 在哪一步拒绝"。

3. `--no-sandbox` 不等于 sandbox 完全关掉

Chromium 至少有三层 sandbox：setuid sandbox、user-namespace sandbox、seccomp-bpf filter。--no-sandbox 主要关掉前两层，仍可能在 seccomp 初始化阶段崩。要全关需要：

--no-sandbox --disable-setuid-sandbox --disable-namespace-sandbox --disable-seccomp-filter-sandbox

但这只用于诊断——生产即便有问题也不要靠这个绕。

4. bundled chromium 不是万能

Playwright 自带的 Chromium 是 Playwright 团队 patched 过的版本，覆盖矩阵窄于 Google 官方 Chrome stable。Azure / 较新 Hyper-V 内核 / 某些 ARM 宿主三者叠加就可能让 bundled chromium 启动崩、而系统 Chrome stable 正常——反过来也成立。生产容器优先用 channel='chrome' 跑系统 Chrome 更保守。

但！这次我们后来发现"换 Chrome stable"本身也不是修复——根因（HOME 缺失）对两个 binary 一视同仁。换 binary 治不了真正的病，只是让症状换了个皮。

5. Dockerfile 一行 `-m` 缺失，藏得最深

useradd -r 不创 home——这是发行版默认行为，dev 阶段本地跑的时候从来不会触发（Mac 跑 docker 不走 rootfs，mount 行为不一样），CI 测试也跑过（其实没跑过——just test 不覆盖 docker build）。这种 bug 只能靠"上 prod 看现象"暴露。

防御：

Dockerfile 优先用 adduser（Debian 系）而不是 useradd，adduser 默认创 home 且交互友好
或者显式 -m -d /home/xxx 让意图不依赖隐式默认
在 CI 里至少跑一次 docker build && docker run 验证 chrome 类应用能起，单纯跑 pytest 不够

完整最终改动

src/backend/Dockerfile：useradd 加 -m -d /home/appuser；chown 补 /home/appuser
docker-compose.dokploy.yml：security_opt: [seccomp=unconfined, apparmor=unconfined]（虽然对 chromium 启动不是必须的，但保险）
sites/kimi-slides.yaml：login_detection_selector 从 .chat-input-editor 换成 .user-avatar-container

附录：诊断脚本模式

发现 strace 末尾 “死前最后几个 syscall” 价值最高，标准化成模板：

docker exec "$CONTAINER" sh -c '
 CHROME=/opt/google/chrome/chrome
 rm -rf /tmp/cp /tmp/strace.log
 timeout 5 strace -f -y \
 -e trace=execve,clone,clone3,prctl,seccomp,unshare,ptrace,personality,\
membarrier,userfaultfd,pidfd_open \
 -o /tmp/strace.log \
 "$CHROME" --headless=new --no-sandbox --disable-dev-shm-usage --disable-gpu \
 --user-data-dir=/tmp/cp about:blank >/dev/null 2>&1
 HANDLER_PID=$(grep "execve.*chrome_crashpad_handler" /tmp/strace.log | head -1 | awk "{print \$1}")
 grep "^$HANDLER_PID " /tmp/strace.log | tail -40
'

-y 会显示 fd 对应的资源；-f 跟踪子进程；trace 列表只列我们关心的 syscall 防止输出爆炸。

任何 chromium 启动崩的现场，这套脚本是首选入口。

gh使用教程

Sun, 12 Apr 2026 21:50:00 +0800

1. 常用命令速查

case

# 创建私有仓库并推送本地代码
gh repo create my-project --private --source=. --push

# 查看帮助与版本
gh --version
gh help
gh <command> --help

# 登录与认证
gh auth login
gh auth status
gh auth logout

# 仓库
gh repo clone owner/repo
gh repo create
gh repo view --web
gh repo fork
gh repo sync

# Pull Request
gh pr create --fill
gh pr list
gh pr view
gh pr checkout 123
gh pr diff
gh pr review --approve
gh pr merge

# Issue
gh issue create
gh issue list
gh issue view 123
gh issue comment 123 --body "补充说明"
gh issue close 123

# GitHub Actions
gh workflow list
gh run list
gh run view <run-id>
gh run watch
gh run download <run-id>

# Release
gh release create v1.0.0
gh release list
gh release view v1.0.0
gh release upload v1.0.0 dist/app.tar.gz

# 浏览器与搜索
gh browse
gh browse 123
gh search prs --author @me
gh search issues --owner your-org

# API 与脚本
gh api user
gh api repos/OWNER/REPO/pulls
gh pr list --json number,title,url

# 配置与效率
gh alias set pv "pr view"
gh config set editor vim
gh extension search
gh extension install owner/gh-extension-name

2. `gh` 是什么

gh 是 GitHub 官方命令行工具，核心价值不是替代 git，而是把原本要在 GitHub 网页上完成的事情搬到终端里。

适合用 git 做的事情：

本地提交、分支切换、变基、合并、查看工作区变更
与任意 Git 远程交互，而不局限于 GitHub

适合用 gh 做的事情：

登录 GitHub 账号
创建和管理 Pull Request、Issue、Release
查看和触发 GitHub Actions
直接调用 GitHub API
安装 GitHub CLI 扩展

最实用的理解方式是：git 管仓库历史，gh 管 GitHub 平台能力。

3. 安装与初始化

安装

常见安装方式如下：

# macOS
brew install gh

# Windows
winget install --id GitHub.cli

# Ubuntu / Debian
type -p curl >/dev/null || sudo apt install curl -y
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | \
 sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | \
 sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh -y

安装后先确认版本：

gh --version

4. 仓库操作

克隆仓库

gh repo clone owner/repo

它本质上还是帮你完成 GitHub 仓库级别的克隆，但写法更统一，也方便后续继续使用 gh。

创建仓库

gh repo create

这个命令会进入交互流程，通常会问你：

仓库名称
是否公开
是否添加 README
是否推送当前目录

如果你想快速把当前项目推到 GitHub，经常很好用。

查看仓库信息

gh repo view
gh repo view --web
gh repo view owner/repo

常见用途：

在终端查看仓库概要
直接在浏览器打开仓库页面
脱离当前目录查看别的仓库

Fork 与同步

gh repo fork
gh repo sync

典型场景：

fork 别人的仓库到自己账号下
在自己的 fork 上开发
上游仓库更新后，用 gh repo sync 同步

如果你平时经常参与开源项目，这两个命令非常顺手。

5. Pull Request 工作流

gh 最有价值的部分之一，就是把 PR 的完整链路搬到命令行里。

创建 PR

gh pr create
gh pr create --fill

--fill 会自动用当前分支的提交信息帮你生成标题和描述，适合已经写好了比较规范 commit message 的情况。

常见流程：

git checkout -b feature/login
git add .
git commit -m "feat: add login page"
git push -u origin feature/login
gh pr create --fill

查看 PR

gh pr list
gh pr view
gh pr view 123
gh pr view --web

适合查看：

当前仓库有哪些 PR
某个 PR 的详情
直接跳转浏览器继续看评论和检查项

切换到某个 PR

gh pr checkout 123

这个命令很适合代码评审场景。你不用先找分支名，直接通过 PR 编号就能把代码拉到本地。

查看差异、检查、评审、合并

gh pr diff 123
gh pr checks 123
gh pr review 123 --approve
gh pr review 123 --comment -b "建议补一个测试"
gh pr merge 123

这一组命令基本覆盖了 PR 审查最常见的动作：

看 diff
看 CI 是否通过
approve / comment / request changes
合并 PR

如果团队流程比较规范，gh 能明显减少频繁切浏览器的次数。

6. Issue 管理

创建与查看

gh issue create
gh issue list
gh issue view 123
gh issue view 123 --web

适合用来做：

快速提 bug
记录待办事项
查看当前仓库未关闭的问题

评论、编辑、关闭

gh issue comment 123 --body "我来处理这个问题"
gh issue edit 123 --add-label bug
gh issue close 123
gh issue reopen 123

如果你把 GitHub Issues 当轻量项目管理工具，这一组命令会非常高频。

7. GitHub Actions 与 CI/CD

gh 对 Actions 的支持很实用，尤其适合你在终端里排查 CI。

查看工作流和运行记录

gh workflow list
gh run list
gh run view <run-id>

观察运行状态

gh run watch

这个命令适合在你刚 push 代码后盯 CI 结果，不用一直刷新网页。

下载产物与重新运行

gh run download <run-id>
gh run rerun <run-id>

常见场景：

下载构建产物
CI 因偶发网络问题失败时重跑
快速定位是哪一步报错

8. Release 管理

如果你的项目通过 GitHub Release 发版本，gh 可以把整个流程命令化。

创建与查看 Release

gh release create v1.0.0
gh release list
gh release view v1.0.0

上传构建产物

gh release upload v1.0.0 dist/app.tar.gz

这在发布二进制、压缩包、安装包时很方便，尤其适合配合脚本或 CI 自动化。

9. `gh api`：把 GitHub API 直接带进终端

很多人低估了 gh api，但它其实是 gh 最强的能力之一。

基本调用

gh api user
gh api repos/OWNER/REPO
gh api repos/OWNER/REPO/issues

如果某个能力暂时没有现成的 gh <group> <subcommand>，往往可以直接退回到 gh api。

搭配 JSON 输出

gh pr list --json number,title,url
gh issue list --json number,title,labels
gh workflow list --json id,name,path,state

这类写法很适合：

给 shell 脚本喂数据
做自动化统计
和 jq 配合筛选字段

例如：

gh pr list --json number,title,author --jq '.[] | {number, title, author: .author.login}'

如果你经常写脚本，建议尽快把 --json、--jq 这套用起来。

10. 提效能力：别名、配置、扩展

alias

gh alias set pv "pr view"
gh alias set pc "pr create --fill"
gh pv
gh pc

适合把高频长命令压缩成自己熟悉的缩写。

config

gh config set editor vim
gh config get editor

最常见的是设置默认编辑器，避免某些命令唤起你不想用的编辑器。

extension

gh extension search
gh extension install owner/gh-extension-name
gh extension list
gh extension upgrade --all

扩展机制可以理解为给 gh 加外挂命令。对于一些官方没内置、但社区已经做好了的能力，扩展通常是最快方案。

11. 推荐的实际使用方式

如果你是个人开发者，可以先掌握这条最实用链路：

gh auth login
gh repo clone owner/repo
git checkout -b feature/xxx
本地开发并提交
git push -u origin feature/xxx
gh pr create --fill
gh pr checks
gh pr merge

如果你负责 CI/CD 或平台维护，再补上这些：

gh workflow list
gh run list
gh run watch
gh release create
gh api

如果你经常参与开源协作，再补上这些：

gh repo fork
gh repo sync
gh issue list
gh pr checkout
gh pr review

12. 常见问题

`gh` 和 `git` 到底怎么分工？

一句话：

git 负责版本控制
gh 负责 GitHub 平台交互

最合理的方式不是二选一，而是组合使用。

为什么有些仓库命令要加 `-R`？

因为 gh 默认优先使用当前目录对应的仓库上下文。如果你不在仓库目录里，或者你想操作别的仓库，就显式指定：

gh pr list -R OWNER/REPO

命令太多记不住怎么办？

先记住三件事：

gh
gh <command>
gh <command> --help

gh 的帮助系统本身就做得很好，遇到不熟悉的子命令时直接查帮助通常最快。

13. 参考资料

Docker Swarm 实战（二）：Traefik 反向代理部署

Sun, 12 Apr 2026 11:00:00 +0800

记录一次真实的生产环境部署过程，包含踩过的坑和解决方案。

环境说明

服务器：阿里云 ECS（Ubuntu）
应用栈：FastAPI 后端 + Next.js 前端 + Celery + Redis
反向代理：Traefik v2.11
容器编排：Docker Swarm
镜像仓库：阿里云 ACR

第一步：安装 Docker

curl -fsSL https://get.docker.com | sh

国内服务器如果无法访问，通过 DaoCloud 镜像拉取：

# 拉取镜像示例
docker pull docker.m.daocloud.io/traefik:v2.11

验证安装：

docker version

第二步：初始化 Docker Swarm

单机部署时，本机既是 manager 也是 worker：

docker swarm init --advertise-addr <服务器公网IP>

执行后会输出一个 docker swarm join 命令，如果以后需要加入 worker 节点可以用它。

第三步：创建 Traefik 公共网络

Traefik 通过 overlay 网络发现各服务，这个网络必须在部署任何 stack 之前创建好：

docker network create --driver overlay --attachable traefik-public

重要：应用的 docker-compose.stack.yml 中 traefik-public 网络标记为 external: true，如果这个网络不存在，docker stack deploy 会直接报错失败。

第四步：准备 Traefik 配置文件

将以下 stack.yml 上传到服务器 /opt/myapp/traefik/stack.yml：

services:
 traefik:
 image: docker.m.daocloud.io/traefik:v2.11
 command:
 - --providers.docker=true
 - --providers.docker.swarmMode=true
 - --providers.docker.endpoint=unix:///var/run/docker.sock
 - --providers.docker.exposedByDefault=false
 - --providers.docker.network=traefik-public
 - --entrypoints.web.address=:80
 - --entrypoints.websecure.address=:443
 - --entrypoints.web.http.redirections.entrypoint.to=websecure
 - --entrypoints.web.http.redirections.entrypoint.scheme=https
 - --certificatesresolvers.letsencrypt.acme.email=${TRAEFIK_ACME_EMAIL}
 - --certificatesresolvers.letsencrypt.acme.storage=/var/lib/traefik/acme/acme.json
 - --certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web
 - --ping=true
 ports:
 - target: 80
 published: 80
 protocol: tcp
 mode: host
 - target: 443
 published: 443
 protocol: tcp
 mode: host
 volumes:
 - /var/run/docker.sock:/var/run/docker.sock:ro
 - /opt/myapp/traefik/acme.json:/var/lib/traefik/acme/acme.json
 networks:
 - traefik-public
 healthcheck:
 test: ["CMD", "traefik", "healthcheck", "--ping"]
 interval: 30s
 timeout: 5s
 retries: 3
 deploy:
 mode: replicated
 replicas: 1
 placement:
 constraints:
 - node.role==manager

networks:
 traefik-public:
 external: true
 name: traefik-public

第五步：准备 ACME 证书存储文件

Traefik 会自动申请 Let’s Encrypt 证书并写入这个文件，文件必须提前创建且权限为 600：

mkdir -p /opt/myapp/traefik
touch /opt/myapp/traefik/acme.json
chmod 600 /opt/myapp/traefik/acme.json

文件内容是空的完全没问题，Traefik 首次启动后会自动填充。

第六步：部署 Traefik

cd /opt/myapp/traefik

TRAEFIK_ACME_EMAIL=你的邮箱@example.com \
docker stack deploy -c stack.yml traefik

验证是否正常运行：

docker stack services traefik
# 应看到 REPLICAS 为 1/1

docker service logs traefik_traefik --tail 20
# 应看到 "Configuration loaded from flags."

踩坑记录

坑 1：Traefik v3 的 swarm provider 与 Docker 29 不兼容

现象：日志持续报错 client version 1.24 is too old. Minimum supported API version is 1.40，服务始终 0/1。

原因：Traefik v3.3.5 的 swarm provider 内部 Docker 客户端使用了旧版 API（1.24），而 Docker 29.x daemon 最低只支持 API 1.40。设置 DOCKER_API_VERSION 环境变量无效，因为 Traefik 的 swarm provider 没有使用该变量。

解决方案：降级到 Traefik v2.11，v2 的 Docker provider 对 Swarm 支持成熟稳定。

同时注意 v2 和 v3 的命令参数不同：

功能	v3	v2
启用 Swarm	`--providers.swarm=true`	`--providers.docker.swarmMode=true`
端点	`--providers.swarm.endpoint`	`--providers.docker.endpoint`
默认不暴露	`--providers.swarm.exposedByDefault`	`--providers.docker.exposedByDefault`

坑 2：静态配置文件与 CLI 参数冲突

现象：同时使用 --configFile=/etc/traefik/traefik.yml 和 CLI 参数时，ACME 存储路径用了配置文件里的旧路径，导致 open /letsencrypt/acme.json: no such file or directory。

解决方案：二选一，不要混用。推荐只用 CLI 参数，去掉 --configFile 和 configs 挂载。

坑 3：SCP 上传目录时目标路径不存在

现象：

scp: realpath /opt/myapp/traefik/: No such file or directory
scp: upload "...": path canonicalization failed

解决方案：上传前先在服务器上创建目录：

ssh root@your-server "mkdir -p /opt/myapp/traefik"

坑 4：host-mode 端口被占用导致 Pending

现象：docker service ps 看到 host-mode port already in use on 1 node，新任务处于 Pending 状态。

原因：滚动更新时旧容器仍在运行占用端口，新容器无法启动。等旧容器退出后会自动恢复正常，不需要手动干预。

部署顺序总结

1. 安装 Docker
2. docker swarm init
3. docker network create --driver overlay --attachable traefik-public
4. 准备 acme.json（touch + chmod 600）
5. docker stack deploy -c stack.yml traefik ← Traefik 先于应用部署
6. docker stack deploy -c docker-compose.stack.yml <app-stack-name>

Traefik 会监听 Docker Swarm 的服务变化，自动根据 deploy.labels 中的配置生成路由规则和申请 HTTPS 证书，无需重启。

Docker Swarm 实战（一）：核心概念与集群管理

Sun, 12 Apr 2026 10:00:00 +0800

系列文章

篇	主题
一（本篇）	核心概念与集群管理
二	Traefik 反向代理部署

为什么选择 Docker Swarm

在容器编排领域，Kubernetes 是行业标准，但对于中小规模项目，Docker Swarm 往往是更务实的选择：

零额外依赖：Docker 自带，无需单独安装
学习曲线平缓：docker-compose.yml 稍加改造就能用于 Swarm
运维成本低：单机也能跑，按需扩展到多节点
足够稳定：生产可用，社区成熟

如果你的业务规模不需要 K8s 的复杂调度能力，Swarm 是一个省心的选择。

核心概念

Node（节点）

Swarm 集群由多个 Docker 主机（Node）组成，分两类角色：

角色	职责
Manager	维护集群状态、调度任务、处理 API 请求
Worker	执行容器任务，不参与调度决策

Manager 节点同时也承担 Worker 职责（可配置为纯 Manager）
生产环境建议部署奇数个 Manager（3 或 5），保证 Raft 共识算法的容错能力
单机部署时，本机同时充当 Manager 和 Worker

Service（服务）

Service 是 Swarm 的基本部署单元，描述"运行什么、运行几份、如何更新"：

Service
├── replicated mode：固定副本数，调度器负责在节点间分配
└── global mode：每个节点各运行一个副本（适合日志收集、监控 agent 等）

Task（任务）

Task 是 Service 的最小执行单元，对应一个运行中的容器实例。调度器将 Task 分配到合适的节点上执行。

Stack（栈）

Stack 是一组相关 Service 的集合，通过 docker-compose.yml（需加 deploy 字段）定义，用 docker stack deploy 一键部署。

Overlay Network（覆盖网络）

Swarm 使用 overlay 网络让不同节点上的容器互相通信，底层通过 VXLAN 封装实现跨主机网络。

安装与初始化

安装 Docker

curl -fsSL https://get.docker.com | sh

国内网络可通过 DaoCloud 镜像安装：

curl -sSL https://get.daocloud.io/docker | sh

初始化 Swarm

# 初始化，指定对外通告的 IP（通常为服务器公网 IP 或内网 IP）
docker swarm init --advertise-addr <IP>

初始化成功后会输出加入集群的命令，记录备用：

To add a worker to this swarm, run the following command:
 docker swarm join --token SWMTKN-1-xxx <IP>:2377

To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.

查看集群状态

docker node ls

输出示例：

ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
abc123 * node-1 Ready Active Leader
def456 node-2 Ready Active
ghi789 node-3 Ready Active Reachable

节点管理

添加节点

# 在 Manager 节点上获取加入 token
docker swarm join-token worker # 获取 worker 加入命令
docker swarm join-token manager # 获取 manager 加入命令

# 在目标机器上执行输出的 join 命令
docker swarm join --token <TOKEN> <MANAGER_IP>:2377

更改节点角色

# Worker 升级为 Manager
docker node promote <NODE_ID>

# Manager 降级为 Worker
docker node demote <NODE_ID>

节点维护与下线

# 将节点置为维护模式（停止接受新任务，现有任务迁移到其他节点）
docker node update --availability drain <NODE_ID>

# 恢复为可调度状态
docker node update --availability active <NODE_ID>

# 从集群中删除节点（需先 drain）
docker node rm <NODE_ID>

服务管理

创建服务

# 基本格式
docker service create \
 --name my-web \
 --replicas 3 \
 --publish published=8080,target=80 \
 nginx:alpine

常用参数：

参数	说明
`--replicas N`	副本数量
`--publish`	端口映射
`--network`	加入指定网络
`--env KEY=VAL`	环境变量
`--constraint`	调度约束（如 `node.role==manager`）
`--limit-cpu / --limit-memory`	资源限制
`--restart-condition`	重启策略
`--update-parallelism`	滚动更新并发数

查看服务

docker service ls # 列出所有服务
docker service ps <SERVICE> # 查看服务的任务列表（各副本状态）
docker service inspect <SERVICE> # 查看服务详细配置
docker service inspect --pretty <SERVICE> # 易读格式

扩缩容

docker service scale my-web=5 # 将副本数调整为 5
docker service scale svc1=3 svc2=2 # 同时调整多个服务

滚动更新

# 更新镜像版本
docker service update --image nginx:1.25 my-web

# 控制更新节奏
docker service update \
 --update-parallelism 2 \  # 每批更新 2 个副本
 --update-delay 10s \  # 每批之间等待 10 秒
 --image nginx:1.25 my-web

更新失败时回滚：

docker service rollback my-web

删除服务

docker service rm my-web

Stack 部署

Stack 是推荐的生产部署方式，用 Compose 文件统一描述整个应用栈。

Compose 文件关键差异

与普通 docker-compose.yml 相比，Stack 文件需要增加 deploy 字段，并且不支持 build（镜像必须提前构建好）：

services:
 api:
 image: myregistry/api:latest
 networks:
 - app-net
 deploy:
 replicas: 2
 update_config:
 parallelism: 1
 delay: 10s
 failure_action: rollback
 restart_policy:
 condition: on-failure
 delay: 5s
 max_attempts: 3
 resources:
 limits:
 cpus: "0.5"
 memory: 512M
 labels:
 - "traefik.enable=true"
 - "traefik.http.routers.api.rule=Host(`api.example.com`)"

networks:
 app-net:
 driver: overlay

部署与更新

# 部署（stack 不存在则创建，已存在则更新）
docker stack deploy -c docker-compose.stack.yml myapp

# 带环境变量
ENV_VAR=value docker stack deploy -c stack.yml myapp

# 查看 stack 中的服务
docker stack services myapp

# 查看 stack 中所有任务
docker stack ps myapp

# 删除整个 stack
docker stack rm myapp

网络管理

创建 overlay 网络

# 基本创建
docker network create --driver overlay my-network

# 可附加（允许独立容器加入，非 Swarm service 也能连接）
docker network create --driver overlay --attachable my-network

网络模式对比

模式	适用场景
`overlay`	Swarm service 之间的跨节点通信（默认）
`host`	直接使用宿主机网络栈，性能最高，但端口冲突风险
`ingress`	Swarm 内置的负载均衡网络（自动创建，无需手动管理）

端口发布模式

ports:
 - target: 80
 published: 80
 protocol: tcp
 mode: host  # host 模式：直接绑定到宿主机，绕过 Swarm 的 ingress 负载均衡

ports:
 - "80:80" # ingress 模式（默认）：通过 Swarm routing mesh 转发，任意节点均可接收流量

配置与密钥管理

Secret（敏感数据）

# 创建 secret
echo "my_db_password" | docker secret create db_password -
docker secret create ssl_cert ./cert.pem

# 在 service 中使用
docker service create \
 --name db \
 --secret db_password \
 postgres:15

在 Compose 文件中：

services:
 db:
 image: postgres:15
 secrets:
 - db_password

secrets:
 db_password:
 external: true # 使用已存在的 secret

Secret 会以文件形式挂载到容器的 /run/secrets/<secret_name>。

Config（非敏感配置）

# 创建 config
docker config create nginx_conf ./nginx.conf

# 在 service 中使用
docker service create \
 --name web \
 --config source=nginx_conf,target=/etc/nginx/nginx.conf \
 nginx

常用运维操作

查看服务日志

docker service logs <SERVICE> # 输出所有副本的日志
docker service logs -f <SERVICE> # 实时跟踪
docker service logs --tail 50 <SERVICE> # 最近 50 行

强制重新部署（不改配置）

docker service update --force <SERVICE>

查看任务失败原因

docker service ps --no-trunc <SERVICE>

--no-trunc 会显示完整的错误信息，方便排查启动失败的原因。

清理已停止的任务

Swarm 默认保留已完成的任务记录，可通过以下方式清理：

docker system prune # 清理未使用的容器、网络、镜像
docker system prune --volumes # 同时清理 volume

常见问题

Q：docker stack deploy 报错 network not found？

A：external: true 的网络必须在 deploy 之前手动创建，否则 Swarm 不会自动创建它：

docker network create --driver overlay --attachable traefik-public

Q：服务副本一直是 0/1，docker service ps 显示 pending？

A：常见原因：

节点资源不足（CPU/内存超出限制）
调度约束无法满足（如 node.role==manager 但 manager 不可用）
host-mode 端口冲突（等旧容器退出自动恢复）
镜像拉取失败（检查仓库权限和网络）

Q：滚动更新后服务异常，如何回滚？

docker service rollback <SERVICE>

Q：单机 Swarm 和 docker compose up 有什么区别？

特性	docker compose	docker stack (Swarm)
高可用	无	副本自动重启、跨节点调度
滚动更新	无	内置，支持回滚
Secret 管理	无	原生支持
扩缩容	手动	`docker service scale`
适用场景	本地开发	生产部署

下一步

Docker Swarm 实战（二）：Traefik 反向代理部署 — 在 Swarm 上部署 Traefik v2，实现 HTTPS 自动证书和路由转发

Self-hosted Runner

Tue, 24 Feb 2026 09:22:30 +0800

实现从 Windows 开发机通过 CI/CD 部署到另一台 Windows 机器的方法

要实现从一台 Windows 开发机通过 CI/CD 直接部署到另一台 Windows 机器，最主流且最稳定的做法是：在目标 Windows 机器上安装一个“自托管运行器 (Self-hosted Runner 或 Agent)”。

这样一来，CI/CD 平台就可以直接向你的目标机器发送指令，让它自动拉取最新代码（或构建好的程序包）、替换旧文件并重启软件。

以下是实现这一目标的标准流程，以目前最常用的 GitHub Actions 为例（GitLab CI/CD 或 Azure DevOps 的原理几乎完全相同）：

开发机上，你编写代码，然后执行 git push 命令将代码推送到云端仓库（如 GitHub）。

云端代码仓库（如 GitHub）检测到代码更新后，会触发 CI/CD 流程。此时，目标机器上运行的后台程序（Runner）接收到来自云端的指令，会自动在本地执行编译、覆盖文件和重启软件的脚本。

在你的目标机器上配置 Runner 是最关键的一步。你需要让目标机器和云端仓库建立连接。具体步骤如下：

在 GitHub 上，进入你的代码仓库，点击 Settings，然后选择 Actions，再进入 Runners 页面。点击 New self-hosted runner，选择 Windows 操作系统及对应的架构（通常是 x64）。

随后，在你的目标 Windows 机器上打开 PowerShell，按照 GitHub 页面上提供的步骤逐行复制并运行命令。这些命令会下载 Runner 程序、进行身份验证并将其注册到你的仓库中。

在配置的最后一步，建议将 Runner 安装为 Windows 服务 (Windows Service)，这样目标机器每次开机都会自动启动 Runner，随时准备接收部署任务。

在目标机器上更新软件时，通常会遇到“文件被占用”的问题。因此，你需要写一个简单的 PowerShell 脚本来处理部署逻辑。例如，你的软件运行在 C:\MyApp：

停止正在运行的软件进程（或 Windows 服务）。
将新编译好的文件复制到 C:\MyApp 并覆盖。
重新启动软件。

在你的开发机上，在项目根目录下创建一个文件夹 .github/workflows/，并在其中新建一个文件（例如 deploy.yml），填入以下内容：

name: Windows Auto Deploy

# 当推送到 main 分支时触发
on:
 push:
 branches: [ "main" ]

jobs:
 build-and-deploy:
 # 这里的 self-hosted 是关键，它告诉 GitHub 在你的目标机器上运行这些步骤
 runs-on: self-hosted 

 steps:
 - name: 1. 获取最新代码
 uses: actions/checkout@v4

 - name: 2. 编译项目 (根据你的语言修改)
 run: |
 echo "开始编译..."
 # 例如 C# 项目: dotnet build -c Release
 # 例如 Node 项目: npm install && npm run build

 - name: 3. 停止当前运行的程序
 run: |
 # 假设你的程序叫 MyApp.exe
 Stop-Process -Name "MyApp" -ErrorAction SilentlyContinue
 # 如果是 Windows 服务，使用: Stop-Service -Name "MyService"

 - name: 4. 部署/覆盖文件
 run: |
 echo "复制文件到运行目录..."
 # 将编译好的产物复制到目标文件夹 (根据实际路径修改)
 Copy-Item -Path ".\bin\Release\net8.0\*" -Destination "C:\Deployments\MyApp" -Recurse -Force

 - name: 5. 重启程序
 run: |
 echo "启动程序..."
 # 启动进程或重启服务
 Start-Process -FilePath "C:\Deployments\MyApp\MyApp.exe"
 # 如果是 Windows 服务，使用: Start-Service -Name "MyService"

在配置 Runner 时，需要注意权限问题。Runner 默认以配置它的用户身份运行。如果你需要操作 C 盘敏感目录或管理 Windows 服务，确保 Runner 对应的用户（或服务账号）具有管理员权限。

此外，如果你的目标机器性能较弱，或者不想安装编译工具链，可以将 CI/CD 拆分为两个 Job：第一个 Job 使用 GitHub 官方的云端 Windows 服务器进行编译并上传产物 (Artifacts)；第二个 Job 运行在 self-hosted 的目标机器上，只负责下载产物并覆盖文件。

Self-hosted Runner 搭建教程

当 GitHub Actions 的免费额度用完，或者需要在特定硬件/内网环境上执行构建时，可以将自己的机器注册为 Self-hosted Runner。它不消耗 GitHub Actions 分钟数，job 会直接运行在你的机器上。

注册 Runner

进入仓库 Settings → Actions → Runners → New self-hosted runner（组织级别则在组织 Settings 中），选择对应的操作系统和架构，页面会生成一段包含一次性 registration token 的命令，照着执行即可。

Linux 安装示例

mkdir actions-runner && cd actions-runner

# 版本号以 GitHub 页面给出的为准
curl -o actions-runner-linux-x64-2.325.0.tar.gz -L \
 https://github.com/actions/runner/releases/download/v2.325.0/actions-runner-linux-x64-2.325.0.tar.gz

tar xzf actions-runner-linux-x64-*.tar.gz

./config.sh --url https://github.com/<用户名>/<仓库> --token <页面生成的token>

# 前台测试运行
./run.sh

# 生产环境建议注册为系统服务
sudo ./svc.sh install
sudo ./svc.sh start

Windows 安装示例

在 PowerShell 中执行（建议在 C:\actions-runner 这类位于驱动器根目录下的短路径中安装；注册为服务时需要在管理员权限下执行）：

# 在驱动器根目录下创建安装目录
mkdir actions-runner; cd actions-runner

# 下载最新 Runner 包；版本号以 GitHub 页面给出的为准
Invoke-WebRequest -Uri https://github.com/actions/runner/releases/download/v2.337.0/actions-runner-win-x64-2.337.0.zip -OutFile actions-runner-win-x64-2.337.0.zip

# 可选：校验 SHA256 哈希，避免下载包损坏
if((Get-FileHash -Path actions-runner-win-x64-2.337.0.zip -Algorithm SHA256).Hash.ToUpper() -ne '1150692afa94e71f872017e254ea55b6eece1eece3fe7e3a6d4c93d0a1b85cfc'.ToUpper()){ throw 'Computed checksum did not match' }

# 解压到当前目录
Add-Type -AssemblyName System.IO.Compression.FileSystem;
[System.IO.Compression.ZipFile]::ExtractToDirectory("$PWD/actions-runner-win-x64-2.337.0.zip", "$PWD")

./config.cmd --url https://github.com/<用户名>/<仓库> --token <页面生成的token>

# 前台测试运行
./run.cmd

# 注册为 Windows 服务并启动
./svc.cmd install
./svc.cmd start

按页面给出的命令完成下载、校验、解压和 config.cmd 配置后，Runner 就会注册到仓库的 Runners 列表中。只要状态显示为 Idle，说明它已经在线并等待接收任务：

配置过程中会给 Runner 起名并选择 label（默认 self-hosted、linux 或 windows 等）。注册为服务后，即使关闭终端或注销用户，Runner 也会在后台常驻。

在 Workflow 中使用

jobs:
 build:
 runs-on: self-hosted  # 或 [self-hosted, linux] / [self-hosted, windows] 指定更细的 label
 steps:
 - uses: actions/checkout@v4
 - name: Build
 run: echo "running on my own machine"

注意事项

安全：公开仓库不要随意接入 self-hosted runner，任何 fork 的 PR 都可能执行代码。建议仅用于私有仓库，或在仓库设置中严格限制 workflow 权限。
环境隔离：job 直接运行在宿主机上，会留下缓存和文件。建议用 Docker 容器或一次性虚拟机运行 Runner，或在每次 job 前后做清理。
服务账户权限：Windows 下 Runner 默认以 NETWORK SERVICE 运行，如果 job 需要 Docker、文件系统或网络共享权限，需在安装服务时指定有权限的账户，或在 services.msc 中修改服务登录账户。
环境依赖：确保 Runner 所在机器已安装构建所需的工具链（Node、Python、Docker 等），且服务账户的 PATH 中可访问。
在线要求：Runner 需要保持在线才能接收任务，建议通过 systemd（Linux）或 Windows 服务常驻运行。

Docker 私有镜像仓库registry

Mon, 23 Feb 2026 00:20:36 +0800

安装和配置

Dokploy ：搭建自带“自动清理”功能的私有 Docker 镜像仓库 — 20260225

在个人服务器上搭建私有 Docker Registry（镜像仓库）是很多开发者的刚需。使用 Dokploy 部署虽然简单，但很多人很快会遇到一个棘手的问题：磁盘空间爆炸。

原生的 Docker Registry 像个“只进不出”的貔貅，默认既不支持删除镜像，删除了也不释放空间。

本文将带你通过 Dokploy 部署一个带 Web 管理界面、支持删除且每晚自动释放磁盘空间的完美私有仓库。

1. 为什么 Registry 的清理这么麻烦？

在开始配置之前，我们需要理解为什么 Docker 官方把 Registry 设计得这么“难用”。很多人发现，即便开启了删除功能，删除了镜像，磁盘占用依然没变。

这是因为 Registry 的清理机制分为两步：

软删除 (Soft Delete)：当你通过 API 或 UI 点击删除时，Registry 只是删除了清单（Manifest）。这就像你在 Windows 上把文件拖进了回收站，文件其实还在磁盘上。
垃圾回收 (Garbage Collection)：这是真正的物理删除。因为 Docker 的镜像是由很多“层（Layers）”组成的，且不同镜像会共享底层。Registry 必须通过扫描全盘，计算引用关系，确认某一层真的没有被任何镜像使用后，才敢真正删除它。

此外，官方默认禁用删除操作（REGISTRY_STORAGE_DELETE_ENABLED: false）主要基于以下考量：

层共享保护：防止误删被其他镜像依赖的基础层。
并发安全：防止在清理时，刚好有新镜像正在推送（Push）导致数据损坏。
不可变基础设施：发布的镜像应当被视为不可变的历史存档。

但在个人或小团队场景下，为了省钱（服务器磁盘贵啊！），我们需要它能够清理。

2. 编写 docker-compose.yml

我们将通过 Dokploy 部署三个服务：

Registry：核心仓库服务。
Auto-Auth：一个辅助容器，启动时生成账号密码文件，然后自动退出。
Registry UI：一个轻量级的 Web 界面，方便我们查看和删除镜像。

在 Dokploy 的 Compose 选项卡中，填入以下配置：

version: '3.8'

# 定义数据卷，持久化存储镜像和认证信息
volumes:
 registry-data:
 registry-auth-data:

# 使用 Dokploy 预置的外部网络
networks:
 dokploy-network:
 external: true

services:
 # 1. 认证辅助服务：生成账号 admin / 密码 123456
 # 启动一次生成文件后就会退出，这是正常的
 auto-setup-auth:
 image: httpd:alpine
 command: /bin/sh -c "htpasswd -Bbn admin 123456 > /auth/htpasswd"
 volumes:
 - registry-auth-data:/auth

 # 2. 核心 Registry 服务
 registry:
 image: registry:2
 container_name: my-private-registry
 restart: always
 networks:
 - dokploy-network
 # 映射端口方便本地调试，生产环境主要靠 Traefik 转发
 ports:
 - "5000:5000"
 environment:
 # 认证配置
 REGISTRY_AUTH: htpasswd
 REGISTRY_AUTH_HTPASSWD_REALM: "Registry Realm"
 REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
 # 反向代理配置
 REGISTRY_HTTP_HEADERS_X_FORWARDED_FOR: true
 REGISTRY_HTTP_HEADERS_X_FORWARDED_PROTO: https
 # 【关键配置】开启删除权限
 REGISTRY_STORAGE_DELETE_ENABLED: "true"
 # 【跨域配置】允许 UI 界面通过浏览器调用 API
 REGISTRY_HTTP_HEADERS_ACCESS_CONTROL_ALLOW_ORIGIN: '[https://registry-ui.zata.cafe]'
 REGISTRY_HTTP_HEADERS_ACCESS_CONTROL_ALLOW_METHODS: '[HEAD,GET,OPTIONS,DELETE]'
 REGISTRY_HTTP_HEADERS_ACCESS_CONTROL_ALLOW_HEADERS: '[Authorization,Accept,Cache-Control]'
 REGISTRY_HTTP_HEADERS_ACCESS_CONTROL_EXPOSE_HEADERS: '[Docker-Content-Digest]'
 volumes:
 - registry-data:/var/lib/registry
 - registry-auth-data:/auth
 depends_on:
 auto-setup-auth:
 condition: service_completed_successfully

 # Traefik 标签：配置域名和 HTTPS
 labels:
 - "traefik.enable=true"
 - "traefik.http.routers.registry.rule=Host(`registry.zata.cafe`)"
 - "traefik.http.routers.registry.entrypoints=websecure"
 - "traefik.http.routers.registry.tls.certresolver=letsencrypt"
 - "traefik.http.services.registry.loadbalancer.server.port=5000"
 # 取消请求体大小限制，防止 Push 大镜像失败
 - "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=0"

 # 3. Web UI 管理界面
 registry-ui:
 image: joxit/docker-registry-ui:latest
 container_name: registry-ui
 restart: always
 networks:
 - dokploy-network
 environment:
 # 删除 REGISTRY_URL，改用下面这两个变量：
 - NGINX_PROXY_PASS_URL=http://my-private-registry:5000
 - SINGLE_REGISTRY=true

 - DELETE_IMAGES=true
 - REGISTRY_TITLE=Zata Registry
 labels:
 - "traefik.enable=true"
 - "traefik.http.routers.registry-ui.rule=Host(`registry-ui.zata.cafe`)"
 - "traefik.http.routers.registry-ui.entrypoints=websecure"
 - "traefik.http.routers.registry-ui.tls.certresolver=letsencrypt"
 - "traefik.http.services.registry-ui.loadbalancer.server.port=80"

注意：请将代码中的 zata.cafe 替换为你自己的域名，并确保 DNS 解析已指向你的服务器。

点击 Deploy 部署应用。

3. 实现自动化清理 (GC)

部署完成后，你现在可以通过 registry-ui.zata.cafe 访问界面，并手动删除不需要的镜像 Tag。但这只是“软删除”。为了释放磁盘空间，我们需要在宿主机上配置定时任务。

步骤 1：创建清理脚本

SSH 登录到你的服务器，创建一个脚本文件：

nano /root/clean_registry.sh

写入以下内容：

#!/bin/bash

echo "Starting Registry Garbage Collection: $(date)"

# 调用容器内的 registry 工具执行垃圾回收
# -m 参数表示同时删除不再被引用的 manifest（清单）
docker exec my-private-registry /bin/registry garbage-collect /etc/docker/registry/config.yml -m

echo "Garbage Collection Finished: $(date)"

保存并退出（Ctrl+O, Enter, Ctrl+X），然后赋予执行权限：

chmod +x /root/clean_registry.sh

步骤 2：配置定时任务 (Crontab)

我们希望在每天凌晨（比如 4 点）没人使用的时候执行清理。

输入命令编辑定时任务：

crontab -e

在文件末尾添加一行：

# 每天凌晨 4:00 执行清理，并将日志输出到文件以便排查
0 4 * * * /root/clean_registry.sh >> /var/log/registry_gc.log 2>&1

4. 最终工作流

完成以上配置后，你的私有仓库工作流变成了这样：

日常开发：正常 docker push 推送镜像。
手动维护：觉得某个镜像版本太老了？打开 registry-ui 网页，点一下垃圾桶图标删除它（此时空间未释放）。
自动瘦身：不用管了，去睡觉吧。凌晨 4 点，服务器会自动运行 GC，扫描并彻底删除那些你标记为删除的文件块，第二天早上起来，磁盘空间就回来了。

总结

通过 Dokploy 配合 Traefik，我们不仅拥有了一个 HTTPS 安全的私有仓库，还加上了可视化管理界面。再配合简单的 Shell 脚本和 Crontab，解决了 Docker Registry 最令人头疼的磁盘占用问题。

Happy Coding! 🐳

Docker 和 Traefik 搭建私有镜像仓库（及踩坑记录）— 202602/23

在 DevOps 流程中，拥有一个私有的 Docker Registry（镜像仓库）是必不可少的。虽然 Docker Hub 很好用，但出于隐私、速度和成本的考虑，自建仓库往往是更好的选择。本文将手把手教你如何使用 Docker Compose 和 Traefik 反向代理搭建一个带 HTTPS 和基础认证的轻量级私有仓库，并重点分析部署过程中最容易遇到的 “Gateway Timeout” 和 “Connection Refused” 等网络问题。

为什么选择这个方案？

轻量级：基于官方 registry:2 镜像，资源占用极小。
安全：通过 Traefik 自动管理 SSL 证书（Let’s Encrypt），并配置 htpasswd 基础认证。
易维护：所有配置通过一个 docker-compose.yml 文件管理。

准备工作

一台安装了 Docker 和 Docker Compose 的 Linux 服务器。
一个域名并解析到服务器 IP（例如：registry.example.com）。
Traefik 已经在运行中（如果你使用的是 Dokploy、Coolify 等面板，Traefik 通常是内置好的）。

核心配置：docker-compose.yml

为了方便演示，我们使用一个技巧：利用临时容器自动生成密码文件，避免手动安装 htpasswd 工具的麻烦。请创建一个目录 my-registry，并在其中新建 docker-compose.yml，内容如下：

version: '3.8'

# 定义数据卷，持久化存储镜像和认证信息
volumes:
 registry-data:
 registry-auth-data:

# 【重点】定义网络
# 这里必须使用 external: true，表示使用外部已经存在的 Traefik 网络
# 如果你用的是 Dokploy，网络名通常是 dokploy-network
# 如果你是自己部署的 Traefik，通常叫 traefik_public 或 proxy
networks:
 dokploy-network:
 external: true

services:
 # 1. 辅助服务：自动生成账号密码
 # 启动后会生成密码文件并存入卷中，然后自动退出
 auto-setup-auth:
 image: httpd:alpine
 # 账号: admin, 密码: 123456 (生产环境请修改！)
 command: /bin/sh -c "htpasswd -Bbn admin 123456 > /auth/htpasswd"
 volumes:
 - registry-auth-data:/auth

 # 2. 核心仓库服务
 registry:
 image: registry:2
 container_name: my-private-registry
 restart: always

 # 【关键点 1】加入 Traefik 所在的网络
 networks:
 - dokploy-network

 # 端口映射（可选，仅用于本地调试，生产环境可注释掉）
 ports:
 - "5000:5000"

 environment:
 # 启用认证
 REGISTRY_AUTH: htpasswd
 REGISTRY_AUTH_HTPASSWD_REALM: "Registry Realm"
 REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
 # 告诉 Registry 它运行在 HTTPS 反向代理后面
 REGISTRY_HTTP_HEADERS_X_FORWARDED_FOR: true
 REGISTRY_HTTP_HEADERS_X_FORWARDED_PROTO: https

 volumes:
 - registry-data:/var/lib/registry
 - registry-auth-data:/auth

 depends_on:
 auto-setup-auth:
 condition: service_completed_successfully

 # 【关键点 2】Traefik 标签配置
 labels:
 - "traefik.enable=true"
 # 修改为你的实际域名
 - "traefik.http.routers.registry.rule=Host(`registry.example.com`)"
 # 指定入口点为 HTTPS
 - "traefik.http.routers.registry.entrypoints=websecure"
 # 启用 TLS (自动申请证书)
 - "traefik.http.routers.registry.tls.certresolver=letsencrypt"
 # 【至关重要】告诉 Traefik 容器内部端口是 5000
 - "traefik.http.services.registry.loadbalancer.server.port=5000"
 # 取消请求体大小限制（防止 docker push 大镜像失败）
 - "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=0"

配置完成后，使用 docker-compose up -d 命令启动服务。

常见问题排查（Troubleshooting）

在部署过程中，你可能会遇到以下几种错误，请根据现象进行排查：

1. 504 Gateway Timeout (网关超时)

现象：浏览器访问域名/v2/，加载很久后显示 504 Gateway Timeout。
原因：这说明 Traefik 接到了请求，但是无法连接到后端的 Registry 容器。这通常是因为 Traefik 和 Registry 不在同一个 Docker 网络 中。Traefik 就像大楼的前台，它想转接电话给 Registry，但发现线路不通。
解决方案：检查 docker-compose.yml 中的 networks 部分。必须确保 Registry 加入了 Traefik 所在的那个网络（通过 docker network ls 查看网络名称）。

2. Context Deadline Exceeded (连接超时)

现象：在使用 Dokploy 或命令行登录时，提示 Client.Timeout exceeded while awaiting headers。
原因：这通常是网络层面的物理隔绝。你的请求根本没有到达服务器，被防火墙拦在了外面。
解决方案：
1. 检查云服务商（AWS/阿里云/腾讯云）的安全组，必须开放 TCP 443 和 80 端口。
2. 检查服务器内部防火墙（如 ufw 或 iptables）。

3. 登录失败或 404 Not Found

现象：访问域名能通，但是 docker login 总是失败，或者页面显示 404。
原因：可能是 Traefik 把流量转发到了错误的端口。Registry 默认监听 5000，而 Traefik 默认转发到 80。
解决方案：确保 labels 中包含指定端口的配置：- "traefik.http.services.registry.loadbalancer.server.port=5000"。

4. 推送镜像失败 (Blob Upload Unknown)

现象：登录成功，但在 docker push 大文件时失败并重试。
原因：Traefik 或 Nginx 默认会限制上传文件的大小。
解决方案：添加中间件配置取消限制：- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=0"。

验证与使用

部署成功后，建议按以下步骤进行测试：

浏览器访问：打开 https://registry.example.com/v2/，应该弹出登录框，输入 admin / 123456，页面显示 {} 即为成功。
Docker 登录：在终端执行 docker login registry.example.com，输入配置的用户名和密码。
推送镜像：
- 给本地镜像打标签：docker tag my-image:latest registry.example.com/my-image:latest
- 推送至仓库：docker push registry.example.com/my-image:latest

总结

搭建私有仓库并不难，难点通常在于网络配置。记住一句话：“Traefik 是网关，防火墙是门卫，网络是内部通道。” 只有这三者都配置正确，你的镜像仓库才能顺畅运行。希望这篇指南能帮你避开常见的陷阱。

概念

镜像仓库命名空间概念详解

在容器化技术日益普及的今天，镜像仓库成为了存储和管理 Docker 镜像的核心基础设施。而在镜像仓库的体系中，命名空间（Namespace） 是一个至关重要却又容易被忽视的概念。本文将带您深入了解命名空间的定义、作用以及最佳实践。

什么是命名空间

命名空间可以理解为镜像仓库中的一种逻辑隔离机制。它类似于文件系统中的文件夹，用于对镜像进行分类和组织。在一个公共或私有的镜像仓库中，命名空间允许不同的用户、团队或项目拥有独立的区域来存储他们的镜像，从而避免命名冲突。

例如，一个完整的镜像地址通常遵循以下格式：

registry/namespace/image-name:tag

其中，namespace 部分就是命名空间。对于个人用户，命名空间通常等同于用户名；对于组织用户，则是组织名称。

为什么需要命名空间

引入命名空间主要为了解决以下几个核心问题：

资源隔离与权限管理 不同的命名空间可以绑定不同的访问控制策略。管理员可以为特定命名空间分配独立的读写权限，确保只有授权人员才能推送或拉取特定镜像，从而实现多租户环境下的安全隔离。
避免命名冲突 在没有命名空间的情况下，所有镜像都必须拥有全局唯一的名称。这显然是不现实的。通过命名空间，不同的团队可以使用相同的镜像名称（例如 web-app），只要它们位于不同的命名空间下（例如 team-a/web-app 和 team-b/web-app），就不会发生冲突。
逻辑组织与分类 随着微服务架构的演进，一个项目可能包含数十甚至上百个镜像。通过合理的命名空间规划，可以将镜像按业务线、环境（开发、测试、生产）或团队进行归类，极大地提升了运维效率。

命名空间的使用场景

在实际操作中，命名空间的应用非常广泛：

个人开发者：通常直接使用个人账户作为命名空间，用于存储个人实验性或开源项目镜像。
企业团队：会创建专门的组织命名空间，如 company-backend、company-frontend，以便区分不同职能团队的产物。
环境隔离：有些团队会使用命名空间来区分环境，例如 proj-dev、proj-prod，虽然更常见的做法是使用 Tag 或不同的仓库实例，但命名空间也是一种可行的隔离手段。

最佳实践建议

为了更高效地管理镜像仓库，建议遵循以下规范：

保持命名简洁：使用小写字母、数字和连字符，避免特殊字符，确保兼容性和易读性。
统一命名规范：团队内部应制定明确的命名规则，例如业务线 - 服务名，防止随意创建导致混乱。
定期清理：定期检查命名空间下的镜像，删除不再使用的旧版本，节省存储空间并减少安全隐患。
权限最小化：仅为必要的人员分配命名空间的写入权限，降低误操作风险。

综上所述，命名空间是镜像仓库管理中不可或缺的一部分。合理使用命名空间不仅能提升工作效率，还能增强系统的安全性和可维护性。希望本文能帮助您更好地规划和使用镜像仓库中的命名空间。

Docker Compose(dev\test\prod)

Wed, 17 Dec 2025 23:05:55 +0800

Docker Compose 全生命周期环境治理深度研究报告

从开发工作流到生产级交付的架构实践

1. 引言：容器编排在软件生命周期中的演进

在云原生技术栈日益成熟的今天，Docker Compose 已超越了其作为“本地开发工具”的初始定位。随着 Docker Compose V2 规范的标准化，它成为定义多容器应用架构的通用语言。本报告旨在剖析如何利用 Compose 的分层合并机制、变量控制体系及不可变基础设施原则，构建一套覆盖 Dev、Test、Prod 的全生命周期治理方案。

2. Docker Compose 配置管理的架构哲学

2.1 核心矛盾：一致性 vs 差异性

架构设计的核心挑战在于维持基础拓扑的一致性（服务依赖、网络别名）与环境配置的差异性（资源限制、暴露端口、卷挂载）。

2.2 覆盖模式（Override Pattern）的数学逻辑

Docker Compose 使用文件名顺序（-f 参数）来决定配置的最终形态。其合并算法（Merge Logic）如下：

标量（Scalars）：直接替换。后加载的文件覆盖先加载的文件（如 image tag, restart 策略）。
映射（Maps）：键值合并。新键追加，旧键覆盖（如 environment, labels）。
序列（Sequences）：追加（Union）。这是最容易出错的地方。例如，如果在 Base 中定义了端口 80，Override 中定义了 8080，结果是两个端口都暴露。
- 例外：挂载卷（Volumes）如果容器内路径相同，则为覆盖。

最佳实践：基座极简原则（Minimalist Base Principle） compose.yaml 应只包含所有环境共有的配置。凡是可能在生产环境需要移除的配置（如调试端口、源代码 Bind Mount），绝对不要写在 Base 文件中。

3. 环境变量（ENV）的生态系统与优先级矩阵

环境变量是导致“配置漂移（Configuration Drift）”的头号原因。必须严格区分 插值（Interpolation） 和 注入（Injection） 两个阶段。

3.1 优先级真值表（Priority Truth Table）

当变量冲突时，Docker Compose V2 遵循以下优先级（由高到低）：

优先级	来源	作用阶段	典型用途
1 (最高)	CLI 参数 (`run -e`)	容器运行时	临时调试、One-off 任务
2	Shell 环境变量 (`export VAR=...`)	插值 & 运行时	CI/CD 流水线注入 Secrets
3	.env 文件	插值 & 运行时	开发者本地默认配置
4	YAML `environment` 列表	运行时	服务特定的显式配置
5	YAML `env_file` 指令	运行时	批量加载非敏感配置
6 (最低)	Dockerfile `ENV` 指令	镜像构建时	镜像层面的默认值

3.2 关键语法技巧

强制校验：${DB_PASSWORD?err} —— 如果未设置变量，阻止 Compose 启动并报错。适用于生产环境防止裸奔。
默认值：${TAG:-latest} —— 允许 CI 传入特定 Tag，本地开发默认为 latest。

4. 环境一：开发环境（Dev）—— 极致反馈循环

目标：代码修改后毫秒级生效，支持断点调试。

4.1 架构策略

利用 compose.override.yaml（默认自动加载）实现“源代码热注入”。

# compose.yaml (基座)
services:
 app:
 # 基础镜像名
 image: my-app:base
 networks:
 - internal

# compose.override.yaml (开发专用)
services:
 app:
 build:
 context: .
 target: development # 多阶段构建：开发阶段
 volumes:
 - ./src:/app/src  # 代码热重载核心
 - /app/node_modules # 匿名卷：防止宿主机覆盖容器依赖
 environment:
 - DEBUG=true
 ports:
 - "8080:8080" # 应用端口
 - "9229:9229" # 调试端口
 command: ["npm", "run", "dev:watch"] # 覆盖启动命令

4.2 性能优化

VirtioFS: macOS/Windows Docker Desktop 用户务必开启 VirtioFS 以解决 Bind Mount IO 性能瓶颈。

5. 环境二：测试环境（Test）—— 自动化质量门禁

目标：瞬态（Ephemeral）、确定性、自动化退出码。

5.1 架构策略

CI 环境不需要 Bind Mount，而是需要构建出的镜像进行测试。利用 --exit-code-from 实现自动化测试编排。

# compose.test.yaml
services:
 sut: # System Under Test
 image: my-app:${CI_COMMIT_SHA} # 确保测试的是当前构建产物
 command: ["npm", "test"]
 depends_on:
 db:
 condition: service_healthy # 关键：等待依赖就绪
 environment:
 - DB_HOST=db

 db:
 image: postgres:15-alpine
 tmpfs: /var/lib/postgresql/data # 使用内存盘，提升速度且自动清理
 healthcheck:
 test: ["CMD-SHELL", "pg_isready -U postgres"]
 interval: 5s
 retries: 5

5.2 CI 流水线命令流

# 1. 构建
docker compose -f compose.yaml -f compose.test.yaml build

# 2. 运行并捕获退出码 (关键步骤)
# --exit-code-from sut: 当 sut 容器退出时，关闭所有容器并返回 sut 的退出码
docker compose -f compose.yaml -f compose.test.yaml up --exit-code-from sut

# 3. 清理 (防止匿名卷残留)
docker compose -f compose.yaml -f compose.test.yaml down -v

6. 环境三：生产环境（Prod）—— 稳定性与安全

目标：不可变基础设施（Immutable Artifacts）、资源隔离、零敏感信息泄露。

6.1 架构策略

严禁包含 build 指令，必须使用预构建并签名的镜像。

# compose.prod.yaml
services:
 app:
 image: registry.com/my-app:v1.2.0 # 锁定具体版本
 restart: unless-stopped
 ports:
 - "80:8080" # 仅暴露服务端口
 environment:
 - NODE_ENV=production
 # 生产级资源限制 (V2 支持非 Swarm 模式)
 deploy:
 resources:
 limits:
 cpus: '1.0' # 硬限制
 memory: 512M  # OOM 熔断阈值
 reservations:
 cpus: '0.2' # 保证资源
 memory: 128M
 # 密钥管理：严禁使用 environment 传递密码
 secrets:
 - db_password

secrets:
 db_password:
 file: ./secrets/prod_db_pwd.txt

6.2 部署命令

# --remove-orphans: 清理旧版本遗留的容器
# -d: 后台运行
docker compose -f compose.yaml -f compose.prod.yaml up -d --remove-orphans

7. 高级主题：数据卷管理的陷阱

7.1 “无法删除”悖论

Docker Compose 的合并逻辑是追加。你无法在 compose.prod.yaml 中编写指令来“删除” compose.yaml 中定义的卷挂载。 解决方案：如果某个卷只在开发环境需要（如 ./src:/app/src），千万不要写在 compose.yaml 里，必须只写在 compose.override.yaml 里。

7.2 生产环境数据持久化

生产环境应使用 命名卷（Named Volumes） 而非绑定挂载，以便于利用 Docker 卷插件进行备份或迁移，并规避宿主机文件权限问题。

8. 总结：全生命周期命令速查表

环节	文件组合	关键参数	核心特征
开发 (Dev)	(默认) `base` + `override`	`up -d`	源码挂载、调试端口开放、多阶段构建 Target: Dev
测试 (CI)	`-f base -f test`	`up --exit-code-from sut`	`tmpfs` 数据、健康检查依赖、自动化退出
生产 (Prod)	`-f base -f prod`	`up -d --remove-orphans`	不可变镜像 Tag、资源限制、Secrets、重启策略

通过严格遵守基座极简原则和分层配置策略，Docker Compose 能够优雅地支撑从单机开发到生产交付的全链路需求，消除环境不一致带来的工程风险。

copier-using

Fri, 12 Sep 2025 15:26:16 +0800

Copier 是什么？

Copier 是一个用于创建和管理项目文件的现代化命令行工具。你可以把它理解为一个强大的“复制粘贴”工具，但它远不止于此。它能根据一个预设的“模板”（template），智能地生成一个新项目，并且在模板更新后，还能将这些更新应用到你已生成的项目中。

它在软件开发领域非常受欢迎，尤其适合用于搭建标准化的项目初始结构，也就是我们常说的“脚手架”（scaffolding）。

核心特性：

项目生成 (Project Generation): 从一个模板快速生成一个新项目。在生成过程中，它会向你提问（例如，项目名称、作者、选择特定功能等），然后根据你的回答填充模板中的变量。
项目更新 (Project Updates): 这是 Copier 相较于其前辈（如 Cookiecutter）最大的优势。当模板本身有了改进或修复（比如，升级了依赖库、修复了安全漏洞），你可以使用 Copier 将这些变更安全地同步到已经生成的项目中，而不会覆盖你自己的代码。
动态与交互式: 通过一系列问题引导用户完成项目配置，并将答案记录在 .copier-answers.yml 文件中，方便未来更新。
版本控制友好: 它与 Git 紧密集成，能很好地处理版本变更和代码合并。
跨平台与语言无关: Copier 本身由 Python 编写，但它可以为任何编程语言（Go, Rust, JavaScript, Python 等）创建项目模板。

简单来说，Copier = 项目脚手架 + 持续更新能力。它解决了传统脚手架工具“一次性生成，后续维护困难”的痛点。

Copier 使用教程

下面，我们将从安装、创建项目、更新项目等环节，一步步教你如何使用 Copier。

1. 安装 Copier

首先，你需要一个 Python 环境。然后使用 pip 或 pipx（推荐）来安装 Copier。pipx 可以将 Copier 安装在独立的环境中，避免污染全局 Python 环境。

使用 pipx (推荐):

# 安装 pipx
python -m pip install --user pipx
python -m pipx ensurepath

# 使用 pipx 安装 copier
pipx install copier

使用 pip:

pip install copier

安装完成后，你可以通过以下命令验证是否成功：

copier --version

2. 从模板创建新项目 (`copier copy`)

Copier 的核心是模板。模板通常是一个 Git 仓库。我们以一个官方推荐的 Python 项目模板为例。

命令格式:

copier copy <模板地址> <你的项目文件夹名称>

实战演练:

假设我们要创建一个名为 my-awesome-project 的新项目。

copier copy gh:copier-org/copier-python-template my-awesome-project

gh:copier-org/copier-python-template 是模板的简写地址，它指向 GitHub 上的 copier-org/copier-python-template 仓库。你也可以使用完整的 https://github.com/copier-org/copier-python-template.git 地址。

执行命令后，Copier 会开始与你交互，提出一系列问题来配置项目：

🎤 What is your project name?
 (Default: My Awesome Project)
└──> My Super FastAPI App # 输入你的项目名

🎤 What is your project description?
 (Default: Awesome project, created with copier-python-template)
└──> A demo project for learning Copier. # 输入描述

... (后续还会有作者、邮箱、选择许可证等问题)

你只需要根据提示回答问题即可。回答完毕后，Copier 会做两件事：

在当前目录下创建一个 my-awesome-project 文件夹。
文件夹内包含了根据你的回答生成的所有项目文件。
同时，文件夹里还会有一个特殊的 .copier-answers.yml 文件，它记录了你刚才的所有回答。这个文件非常重要，是未来项目更新的关键！

.copier-answers.yml 文件示例:

# Changes here will be overwritten by Copier
_commit: v0.2.2
_src_path: gh:copier-org/copier-python-template
author_email: your_email@example.com
author_name: Your Name
project_description: A demo project for learning Copier.
project_name: My Super FastAPI App
...

3. 更新现有项目 (`copier update`)

这是 Copier 的“杀手级”功能。假设一段时间后，copier-python-template 模板的作者发布了一个新版本，修复了一些 Bug 并增加了一些新功能。你想把这些更新应用到你的 my-awesome-project 中。

操作非常简单：

首先，进入你的项目目录：

cd my-awesome-project

然后，执行更新命令：

copier update

Copier 会自动执行以下步骤：

读取 .copier-answers.yml 文件，找到原始模板地址和上次生成时的版本。
检查模板仓库是否有新版本。
使用你之前回答过的答案，重新生成一份最新的项目文件。
将新生成的文件与你当前的项目文件进行对比，并尝试智能合并。

在合并过程中，如果遇到冲突（例如，模板的某个文件和你自己修改过的文件内容不一致），Copier 会生成标准的 .rej 冲突文件，或者如果你在 Git 仓库中，它会产生 Git 冲突标记，让你手动解决。

更新时的注意事项:

强烈建议在执行 copier update 前，确保你的项目已经提交到 Git。这样即使更新出现问题，你也可以轻松回滚。
Copier 会尽力保留你自己的代码，但最佳实践是，尽量不要修改由模板直接生成且预计会频繁更新的配置文件（除非你清楚自己在做什么）。

4. 创建自己的模板

如果你想创建自己的项目模板，也非常简单。

创建一个标准的项目结构。例如，一个包含 README.md, .gitignore, src/ 等文件的项目。
将需要动态替换的内容改为 Jinja2 语法。
- 文件名可以包含变量，例如 {{ project_name }}/main.py。
- 文件内容也可以包含变量，例如 README.md 中可以这样写：
```
# {{ project_name }}

{{ project_description }}
```

创建一个 copier.yml (或 copier.yaml) 文件。这个文件用来定义 Copier 需要向用户提出的问题。

copier.yml 示例:

# 定义问题
project_name:
 type: str
 help: What is your project name?

project_description:
 type: str
 help: What is your project description?
 default: "A cool project."

# 定义模板渲染后要执行的命令
_tasks:
 - git init
 - git add .
 - git commit -m "Initial commit from copier template"

这里定义了两个问题：project_name 和 project_description。用户在生成项目时回答的答案会分别赋值给这两个变量。

将模板推送到 Git 仓库（如 GitHub），然后你就可以像之前一样使用 copier copy 来从你的模板创建新项目了。

总结

对于使用者: Copier 是一个能让你轻松使用标准化项目模板并保持模板同步更新的强大工具。只需 copier copy 创建和 copier update 更新。
对于模板维护者/团队: Copier 是统一团队技术栈、规范项目结构、分发最佳实践的利器。通过维护一个中央模板，所有团队成员都可以快速启动项目并享受持续的模板升级。

你最开始提到的那个脚本，正是在 Copier 这个大生态系统下的一个自动化辅助工具。它解决了 .env 文件通常不适合使用 Jinja2 模板直接渲染的问题，通过在 Copier 更新后运行脚本，间接地将 .copier-answers.yml 中的配置同步到 .env 文件中，实现配置的无缝更新。这正是 Copier 强大扩展性的体现。

build x86 image in ARM MAC platform and devolopmet to remote server

Thu, 11 Sep 2025 16:50:53 +0800

在 ARM Mac 上构建 x86 镜像并部署至远程服务器的终极指南

这份指南涵盖了从在 Apple Silicon (M1/M2/M3) Mac 上交叉编译构建 x86 (amd64) Docker 镜像，到将其以不同方式保存和部署的完整流程。

1. 在 ARM Mac 上构建 x86 镜像

由于本地 Mac 是 arm64 架构，而目标服务器通常是 x86_64 (即 amd64)，我们需要进行交叉编译构建。Docker Desktop for Mac 内置的 QEMU 模拟器和 buildx 工具使这一切变得简单。

准备工作

一台 Apple Silicon 芯片的 Mac。
安装最新版的 Docker Desktop for Mac。

构建步骤

创建 Dockerfile 在一个空的项目目录中，创建一个 Dockerfile 文件。明确指定基础镜像的平台是一个好习惯。

# Dockerfile
# 使用 --platform 标志确保拉取的是 amd64 版本的镜像
FROM --platform=linux/amd64 ubuntu:22.04

LABEL maintainer="Your Name"
LABEL target_architecture="x86_64/amd64"

# RUN 指令会在 QEMU 模拟的 x86 环境中执行
RUN apt-get update && apt-get install -y curl

# 验证架构
RUN echo "本镜像架构为:" && uname -m

CMD ["bash"]

执行构建命令 使用 docker build 命令并附带 --platform 标志来指定目标架构。
```
# 在包含 Dockerfile 的目录下执行
# 将 my-x86-app:1.0 替换为你想要的镜像名和标签
docker build --platform linux/amd64 -t my-x86-app:1.0 .
```
- 如果构建的时候网络失败，可以先使用 docker pull –platform linux/amd64 <镜像名>:<标签> 提前拉取镜像
- --platform linux/amd64: 核心参数，告诉 Docker 你要构建的是 x86 镜像。
- 构建过程会比原生编译慢，因为指令需要通过 QEMU 模拟执行。
验证本地镜像架构 构建完成后，镜像会保存在你的本地。使用 docker inspect 来确认其架构。
```
docker inspect my-x86-app:1.0 | grep Architecture
```
预期输出应为:
```
 "Architecture": "amd64",
```

2. 保存与分发构建好的镜像

现在你本地有了一个 x86 架构的镜像 my-x86-app:1.0，接下来可以根据需求将其分发出去。

方案 A: 推送到镜像仓库（团队协作/CI/CD 推荐）

这是最规范、最通用的方法，适用于所有需要网络访问的场景。

标记镜像 (Tag) 为镜像打上符合仓库规范的标签。以 Docker Hub 为例，格式为 <用户名>/<仓库名>:<标签>。
```
docker tag my-x86-app:1.0 your-dockerhub-username/my-x86-app:1.0
```
登录仓库
```
docker login
```
推送镜像 (Push)
```
docker push your-dockerhub-username/my-x86-app:1.0
```
推送后，任何有权限的人或服务器都可以通过 docker pull 命令拉取此镜像。

方案 B: 直接传输到另一台服务器（最高效的 P2P 方式）

如果你想将在本地构建好的镜像，快速地发送到一台已经配置好 SSH 访问的服务器上，这是最佳选择。此方法不依赖镜像仓库，也不在本地产生中间文件。

使用 docker save 和 ssh 管道流式传输 这条命令将本地镜像打包后，通过 SSH 管道直接在远程服务器上加载。
```
# 将 your-user@your-server 替换为你的 SSH 登录信息
docker save my-x86-app:1.0 | ssh your-user@your-server 'docker load'
```
工作原理:
- docker save my-x86-app:1.0: 将镜像打包成 tar 流输出到标准输出。
- |: 管道，将左侧命令的输出作为右侧命令的输入。
- ssh ... 'docker load': 连接到远程服务器，并在服务器上执行 docker load 命令，该命令从标准输入读取 tar 流并加载镜像。
验证 SSH 登录到你的服务器 ssh your-user@your-server，然后运行 docker images，即可看到 my-x86-app:1.0。

方案 C: 导出为文件后手动传输（离线场景）

适用于完全离线的环境，或者需要将镜像文件存档的场景。

保存为 .tar 文件

docker save -o my-x86-app-1.0.tar my-x86-app:1.0

拷贝文件 使用 scp 或其他工具将 my-x86-app-1.0.tar 文件传输到服务器。
```
scp my-x86-app-1.0.tar your-user@your-server:/path/to/destination/
```

在服务器上加载 SSH 登录服务器后，从文件加载镜像。

ssh your-user@your-server
# 在服务器上执行
docker load -i /path/to/destination/my-x86-app-1.0.tar

附录: 关于 `docker context` 的说明

docker context 是一个强大的工具，但它的用途与上述方案 B 和 C 不同。

docker context 的作用: 它是用来切换 Docker CLI 的控制目标。当你 docker context use your-server 时，你的本地终端就变成了远程服务器 Docker 的遥控器。

使用场景: 如果你希望构建过程本身就发生在远程服务器上（利用服务器的 CPU 和原生 x86 架构），那么就应该先切换 context，再运行 docker build。

# 1. 切换控制目标到服务器
docker context use your-server

# 2. 本地的源码会自动上传到服务器，并在服务器上完成构建
docker build -t my-app-built-on-server:1.0 .

# 3. 操作完成后切回本地
docker context use default

这与“在本地构建，然后把产物（镜像）发送过去”是两种不同的工作流。

希望这份整合后的指南能清晰地解答你的所有疑问！

Playwright 使用实践与本地浏览器 Profile 避坑

Sun, 31 Aug 2025 08:13:49 +0800

一个代价很大的坑

我之前写 Playwright 程序时，希望它直接使用电脑上安装的浏览器和已有登录状态，于是让它复用了本地 Chrome 的用户目录。结果自动化运行后，日常浏览器里的历史记录全部消失了。

这个经历里最容易混淆的是两件事：

使用本机安装的 Chrome 程序：通常没问题。
使用日常 Chrome 的用户数据目录（Profile）：风险很高，不应该这样做。

Playwright 默认创建隔离的 BrowserContext，其行为类似一个全新的无痕环境，不会读取日常 Chrome 的历史记录、Cookie 或扩展。只有在使用 launch_persistent_context() 并把 user_data_dir 指向真实 Chrome 用户目录时，自动化程序才会直接读写日常浏览数据。

为什么真实 Profile 可能出问题

Chrome 的用户目录中不只是 Cookie，还包含：

History：浏览历史数据库
Cookies：Cookie 数据库
Login Data：保存的登录信息
Bookmarks：书签
Preferences：浏览器配置
扩展、缓存和站点本地存储

这些文件中有不少是 SQLite 数据库。普通 Chrome 和 Playwright 同时访问同一个 Profile，可能发生文件锁冲突、数据库损坏或配置覆盖。如果脚本还带有清理、复制、初始化目录的逻辑，就可能直接覆盖原数据。

另外，Chrome 现在也限制自动化工具访问默认用户目录。Playwright 官方明确建议：不要把日常 Chrome 的主 User Data 目录传给自动化程序，而应创建独立目录作为自动化 Profile。

错误示例：直接复用日常 Chrome Profile

macOS 上，Chrome 的用户数据通常位于：

~/Library/Application Support/Google/Chrome

不要这样写：

from pathlib import Path

from playwright.sync_api import sync_playwright


chrome_user_data_dir = (
 Path.home() / "Library/Application Support/Google/Chrome"
)

with sync_playwright() as playwright:
 context = playwright.chromium.launch_persistent_context(
 user_data_dir=chrome_user_data_dir,
 channel="chrome",
 headless=False,
 )
 page = context.new_page()
 page.goto("https://example.com")
 context.close()

这里的危险点不是 channel="chrome"，而是 user_data_dir 指向了日常使用的 Chrome 数据目录。

还要注意，chrome://version 中显示的“个人资料路径”可能是：

.../Google/Chrome/Default

而 Chromium 启动参数所需的 user_data_dir 是它的父目录：

.../Google/Chrome

不要因为两者层级不同，就尝试把 Default 或它的父目录逐个传给脚本测试；它们都属于真实浏览数据。

正确方案一：使用系统 Chrome，但创建专用 Profile

如果需要有头浏览器、持久化 Cookie 或长期登录状态，可以为自动化单独创建目录：

from pathlib import Path

from playwright.sync_api import sync_playwright


automation_profile_dir = Path.cwd() / ".playwright-profile"
automation_profile_dir.mkdir(parents=True, exist_ok=True)

with sync_playwright() as playwright:
 context = playwright.chromium.launch_persistent_context(
 user_data_dir=automation_profile_dir,
 channel="chrome",
 headless=False,
 )
 page = context.pages[0] if context.pages else context.new_page()
 page.goto("https://example.com")
 context.close()

这段代码中：

channel="chrome" 使用本机安装的 Google Chrome。
.playwright-profile 只供自动化程序使用。
关闭后 Cookie、本地存储等仍会保留，下一次运行可以继续使用。
日常 Chrome 和自动化 Chrome 的数据完全分离。

应把专用 Profile 加入 .gitignore，避免将 Cookie 或凭据提交到仓库：

.playwright-profile/

正确方案二：只保存登录状态

如果只是运行测试，通常不需要保存整个浏览器 Profile。更轻量的做法是登录一次后导出 storage_state：

from pathlib import Path

from playwright.sync_api import sync_playwright


auth_state_path = Path("playwright/.auth/user.json")
auth_state_path.parent.mkdir(parents=True, exist_ok=True)

with sync_playwright() as playwright:
 browser = playwright.chromium.launch(headless=False)
 context = browser.new_context()
 page = context.new_page()

 page.goto("https://example.com/login")
 # 在这里完成登录。

 context.storage_state(path=auth_state_path)
 browser.close()

后续运行时加载它：

from playwright.sync_api import sync_playwright


with sync_playwright() as playwright:
 browser = playwright.chromium.launch()
 context = browser.new_context(
 storage_state="playwright/.auth/user.json",
 )
 page = context.new_page()
 page.goto("https://example.com")
 browser.close()

storage_state 主要保存 Cookie、localStorage 和 IndexedDB，比复制整个 Profile 更适合自动化测试。但这个文件仍可能包含有效登录凭据，也必须加入 .gitignore：

playwright/.auth/

普通隔离模式

不需要复用登录状态时，直接使用 Playwright 默认的隔离模式最安全：

from playwright.sync_api import sync_playwright


with sync_playwright() as playwright:
 browser = playwright.chromium.launch(
 channel="chrome",
 headless=False,
 )
 context = browser.new_context()
 page = context.new_page()
 page.goto("https://example.com")
 browser.close()

每个新建的 BrowserContext 都是独立的干净环境。关闭 Context 后其中的临时 Cookie 和本地存储会被丢弃，但不会触碰日常 Chrome Profile。

安全检查清单

在运行任何复用浏览器状态的 Playwright 程序前，至少检查以下事项：

user_data_dir 是否指向专用目录，而不是 Chrome、Edge 或 Chromium 的日常用户目录。
普通浏览器和 Playwright 是否会同时打开同一个 Profile。
cleanup 逻辑是否可能对未校验的路径执行 rmtree()、rm -rf 或覆盖复制。
是否可以用 storage_state 替代整个持久化 Profile。
自动化 Profile 和认证状态文件是否已加入 .gitignore。
重要浏览器数据是否有同步或系统备份。

如果程序必须清理自动化 Profile，应使用固定的专用路径，并在删除前验证目录名称。不要对来自环境变量或外部输入、尚未解析和校验的路径直接执行递归删除。

历史记录消失后的排查

发现历史记录不见后，先不要继续频繁启动 Chrome：

完全退出普通 Chrome 和 Playwright。
备份整个 Chrome 用户目录。
打开 chrome://version，确认普通 Chrome 当前使用的是 Default、Profile 1 还是其他 Profile。
检查各 Profile 下是否仍有 History 文件。
检查 Chrome Sync、Time Machine 或其他系统备份。

macOS 上常见的历史数据库位置包括：

~/Library/Application Support/Google/Chrome/Default/History
~/Library/Application Support/Google/Chrome/Profile 1/History

History 是 SQLite 数据库。如果只是切换到了空 Profile，原数据可能仍在其他目录；如果数据库已被覆盖或重新创建，则需要从同步或备份中恢复。

总结

使用 Playwright 时要区分“浏览器程序”和“浏览器数据”：

想使用本地 Chrome：设置 channel="chrome"。
想保存自动化登录状态：使用专用 user_data_dir。
只想复用测试登录态：优先使用 storage_state。
永远不要让自动化程序直接操作日常 Chrome Profile。

参考资料

github release

Thu, 01 May 2025 01:28:06 +0800

关于版本的管理可以参考： https://www.bilibili.com/video/BV1Ee411W79K

GitHub Release 是 GitHub 上用来标记项目可发布版本的一种方式。它可以包含该版本的源代码快照、编译好的二进制文件以及相关的发行说明。创建 Release 有助于用户清晰地了解项目的版本历史和获取特定版本的可执行文件或库。

为什么使用 GitHub Release？

版本管理： 清晰地标记项目的不同版本，方便追溯和管理。
软件分发： 提供稳定版本的下载链接，方便用户获取和使用。
发行说明： 在 Release 中包含详细的说明，介绍该版本的特性、改进、Bug 修复等。
自动化： 可以结合 CI/CD 工具实现自动化 Release 发布。

在创建 GitHub Release 之前，你需要满足以下条件：

拥有一个 GitHub 账号。
拥有一个 GitHub 仓库。
对该仓库有写入权限。
通常情况下，你需要有一个 Git Tag 与 Release 关联。Tag 用于标记代码库中的某个特定的提交（commit），代表着该版本代码的状态。

有两种主要的方式来创建 GitHub Release：通过 GitHub 网页界面和通过 Git 命令行工具（结合 GitHub CLI）。

方法一：通过 GitHub 网页界面创建 Release

这是最直观和常用的方法。

步骤 1：进入你的仓库页面

在浏览器中打开你的 GitHub 仓库主页。

步骤 2：创建新的 Release

“Create a new release"（创建新 Release），点击这个按钮。

步骤 3：选择或创建 Tag

在新 Release 页面，你需要关联一个 Git Tag。

选择现有 Tag： 点击 “Choose a tag”（选择一个标签）下拉菜单，选择一个已经存在的 Tag。
创建新 Tag： 在输入框中直接输入你想要创建的新 Tag 名称（例如 v1.0.0）。输入后，会显示 “Create new tag on publish"（发布时创建新标签）。

重要提示： Tag 的命名通常遵循 Semantic Versioning 规范，格式通常是 MAJOR.MINOR.PATCH（大版本，小版本，bug修复版本），例如 v1.0.0、v1.2.3 等。建议在 Tag 前加上 v。

步骤 4：选择目标分支 (如果创建新 Tag)

如果你在步骤 4 中创建了一个新的 Tag，你需要选择这个 Tag 将关联到哪个分支上的最新提交。通常情况下，你会选择你的主分支（如 main 或 master）。点击 “Target”（目标）下拉菜单进行选择。

步骤 5：填写 Release 标题和描述

Release title (发行标题): 输入你的 Release 的标题，通常与 Tag 名称相同或稍作描述（例如 “Version 1.0.0 Release”）。
Describe this release (描述此发行版): 在这里填写详细的发行说明（Release Notes）。你可以使用 Markdown 格式来美化你的说明。发行说明通常包括：
- 新功能 (New Features)
- 改进 (Improvements)
- Bug 修复 (Bug Fixes)
- 已知问题 (Known Issues)
- 重大变化 (Breaking Changes) (如果适用)
- 致谢 (Acknowledgements) (如果适用)

步骤 6：自动生成 Release Notes (可选)

GitHub 可以根据最近的提交历史自动生成 Release Notes。在描述框上方，点击 “Generate release notes"（生成发行说明）按钮。你可以基于生成的笔记进行修改和完善。

步骤 7：上传二进制文件 (可选) 这只能上传25M，Github CLi可以2G

如果你的 Release 包含编译好的可执行文件、安装包或其他二进制文件，可以在 “Attach binaries by dropping them here or selecting them"（通过将二进制文件拖放到此处或选择它们来附加）区域上传。直接将文件拖放到该区域，或者点击选择文件。

步骤 8：选择 Release 类型 (可选)

This is a pre-release (这是一个预发行版): 如果这个 Release 是一个测试版本、Beta 版本或 RC (Release Candidate) 版本，勾选此选项。预发行版会在 Release 列表中有特殊的标记。
Set as the latest release (设置为最新发行版): 默认情况下，新发布的 Release 会被标记为最新发行版。如果你发布的是一个旧版本或一个特殊的 Release，可以取消勾选此选项。

步骤 9：创建讨论 (可选)

如果你的仓库开启了 GitHub Discussions 功能，你可以选择为这个 Release 创建一个讨论。勾选 “Create a discussion for this release"（为此发行版创建讨论），并选择一个讨论分类。

步骤 10：发布 Release

Publish release (发布发行版): 如果你准备好将 Release 公开，点击此按钮。
Save draft (保存草稿): 如果你还没有准备好发布，想稍后再完善，点击此按钮将 Release 保存为草稿。草稿状态的 Release 只有仓库的协作者可见。

发布后，你的 Release 将会在仓库的 Releases 页面列出，并且与你关联的 Tag 也会被创建（如果你创建了新 Tag）。

方法二：通过 Git 命令行和 GitHub CLI 创建 Release

对于习惯使用命令行或需要自动化发布流程的用户，可以使用 Git 命令创建 Tag，然后结合 GitHub CLI 来创建 Release。

前提条件：

安装并配置好 Git。
安装并认证 GitHub CLI (https://cli.github.com/)。

CLI可以看：GitHub CLI 命令行工具（gh)

步骤 1：在本地仓库创建并推送 Tag

首先，在你的本地 Git 仓库中创建并推送一个 Tag。

# 切换到你想要打 Tag 的 commit (可选，如果不是最新的 commit)
# git checkout <commit_hash>

# 创建一个轻量级 Tag (不推荐用于 Release)
# git tag <tag_name>

# 创建一个附注 Tag (推荐用于 Release，可以包含说明信息)
git tag -a <tag_name> -m "发行说明"

# 推送 Tag 到远程仓库
git push origin <tag_name>

例如：

git tag -a v1.0.0 -m "Initial release"
git push origin v1.0.0

如果想要删除tag，使用下面的命令

# 删除本地tag
git tag -d v1.0.0

# 删除远程tag
git push origin --delete v1.0.0

步骤 2：使用 GitHub CLI 创建 Release

在 Tag 推送到 GitHub 后，你可以使用 GitHub CLI 命令来创建 Release。

gh release create <tag_name> [flags]

一些常用的 flag：

-t, --title <string>: 设置 Release 的标题。
-n, --notes <string>: 设置 Release 的描述/发行说明。
-F, --notes-file <file>: 从文件中读取 Release 的描述/发行说明。
-d, --draft: 将 Release 创建为草稿。
-p, --prerelease: 将 Release 标记为预发行版。
--latest=false: 不将此 Release 设置为最新发行版。
<filename> | <pattern>...: 指定要上传到 Release 的资产文件。

例如，创建一个包含描述并上传一个文件的 Release：

gh release create v1.0.0 --title "Version 1.0.0" --notes "This is the first release." my_app.zip

如果你的发行说明比较长，可以将其写入一个文件（例如 release_notes.md），然后使用 -F 参数：

gh release create v1.0.0 --title "Version 1.0.0" -F release_notes.md my_app.zip

如果你只创建 Tag，然后想基于该 Tag 在 GitHub 上起草 Release，也可以直接去网页界面操作，选择刚刚推送的 Tag。但是网页只能上传25MB的附件

通过命令行编辑和删除 Release：

GitHub CLI 也提供了编辑和删除 Release 的命令：

编辑 Release：gh release edit <tag_name> [flags]
删除 Release：gh release delete <tag_name>

总结

创建 GitHub Release 是项目版本管理和软件分发的重要环节。你可以选择使用直观的网页界面进行操作，也可以通过命令行工具实现更灵活和自动化的流程。无论哪种方式，核心都是为代码库的特定状态（通过 Git Tag 标记）创建一个带有详细说明和可选附件的版本发布。

希望这个详细教程对你有帮助！

git-submodule-子模块

Tue, 29 Apr 2025 11:10:22 +0800

这是一份关于 Git Submodule（子模块）的详细教程，包括概念、使用场景、常用命令以及详细的可执行代码示例。

Git Submodule 允许你将一个 Git 仓库作为另一个 Git 仓库的子目录。这在你有一个主项目依赖于其他独立开发的库或项目时非常有用。子模块会固定在你指定的一个特定的提交（commit）上，而不是分支的最新状态。

知识点总结

Git Submodule 记录的是子模块仓库中一个特定的提交

Git Submodule 的一个核心概念是：主仓库记录的是子模块仓库中一个特定的提交（commit），而不是跟踪子模块的某个分支的最新状态。

这意味着当你使用 git submodule add <远程仓库URL> 命令时：

Git 会克隆远程子模块仓库到指定的路径。默认情况下，Git 会检出子模块仓库的默认分支（通常是 main 或 master）。最重要的一点：主仓库会记录下子模块仓库在那个默认分支上当前的最新提交的 SHA-1 值。

为什么是这样？

这种设计是为了保证主项目的稳定性。主项目依赖于子模块的一个确定版本。如果主项目仅仅跟踪子模块的某个分支（比如 main），那么子模块的任何新提交都可能在你不经意间破坏主项目的功能。通过锁定到特定的提交，你可以精确控制主项目使用的子模块代码版本，确保每次克隆或更新主项目时，子模块都处于预期的状态。

如何指定添加子模块时使用的分支或标签？

如果你不想使用子模块仓库的默认分支，可以在 git submodule add 命令中使用 -b 选项指定一个特定的分支：

git submodule add -b <分支名> <远程仓库URL> <子模块在主仓库中的路径>

示例：指定 develop 分支

假设你想添加子模块，并使用其 develop 分支的当前提交：

git submodule add -b develop https://github.com/your-username/your-submodule-repo.git submodule_directory

这样，Git 会克隆子模块仓库，检出 develop 分支，然后主仓库记录 develop 分支当前的最新提交。

你也可以指定一个标签（tag）：

git submodule add -b <标签名> <远程仓库URL> <子模块在主仓库中的路径>

更新子模块时如何处理分支？

当你运行 git submodule update –remote 命令来更新子模块时：

Git 会进入子模块目录。

它会拉取子模块远程仓库的最新提交。

默认情况下，它会根据 .gitmodules 文件中记录的信息（如果添加时指定了 -b 分支，则使用该分支；否则使用远程仓库的默认分支）找到该分支的最新提交。

然后，它会将子模块的工作树更新到该分支的最新提交，并更新主仓库对子模块的引用到这个新的提交。

为什么使用 Git Submodule？

管理外部依赖： 当你的项目依赖于第三方库或其他内部独立项目时，可以使用子模块来包含它们，而不是直接复制代码。
分离关注点： 将大型项目拆分成更小的、可管理的独立仓库。
版本控制依赖： 精确控制主项目使用的外部依赖的版本（通过指定特定的提交）。

Git Submodule 的一些注意事项：

复杂性增加： 使用子模块会增加工作流程的复杂性，特别是对于不熟悉子模块的团队成员。
更新子模块： 子模块不会随主项目自动更新到最新版本，需要手动更新。
克隆的特殊性： 克隆包含子模块的项目需要额外的步骤。

具体教程

准备工作：创建示例仓库

为了演示，我们需要创建两个 Git 仓库：一个作为主仓库（parent），另一个作为子模块仓库（submodule）。

创建子模块仓库 (submodule_repo):

# 创建一个目录作为子模块仓库
mkdir submodule_repo
cd submodule_repo

# 初始化 Git 仓库
git init

# 创建一个示例文件
echo "This is the submodule content." > submodule_file.txt

# 添加并提交
git add .
git commit -m "Initial commit for submodule"

# (可选) 如果你使用 GitHub 或 Gitee，可以创建一个远程仓库并关联
# git remote add origin <你的远程仓库地址>
# git push -u origin master

创建主仓库 (parent_repo):

# 回到上一级目录
cd ..

# 创建一个目录作为主仓库
mkdir parent_repo
cd parent_repo

# 初始化 Git 仓库
git init

# 创建一个示例文件
echo "This is the parent content." > parent_file.txt

# 添加并提交
git add .
git commit -m "Initial commit for parent"

# (可选) 如果你使用 GitHub 或 Gitee，可以创建一个远程仓库并关联
# git remote add origin <你的远程仓库地址>
# git push -u origin master

现在我们有了两个本地 Git 仓库：parent_repo 和 submodule_repo。

1. 添加子模块

在主仓库 parent_repo 中，我们将 submodule_repo 添加为一个子模块。

打开终端，进入 parent_repo 目录：

cd parent_repo

使用 git submodule add 命令添加子模块。语法是：git submodule add <子模块仓库地址> <子模块在主仓库中的路径>

如果你的子模块仓库是本地的，可以使用相对或绝对路径。如果是远程仓库（如 GitHub），使用其 URL。

示例：添加本地子模块

因为 Git 的安全设置默认禁止通过 file:// 协议（也就是直接的本地文件路径）进行克隆，这包括添加本地子模块。

这是 Git 为了防止某些安全风险而设置的。当你使用相对路径 ../submodule_repo 时，Git 内部会将其解析为 file:// 协议来尝试克隆。

因此可以通过配置全局允许file协议解决

# 任何目录下执行，写入配置
git config --global protocol.file.allow always



## 如果想取消
git config --global --unset protocol.file.allow

假设 submodule_repo 目录与 parent_repo 目录在同一级。

# 在主仓库目录，添加子模块
git submodule add ../submodule_repo submodule_directory

../submodule_repo: 子模块仓库的路径。
submodule_directory: 子模块在 parent_repo 中的存放路径。

执行此命令后，你会看到类似以下的输出：

Cloning into 'submodule_directory'...
done.

查看变化：

运行 git status，你会发现有两项变化：

.gitmodules 文件被创建。
submodule_directory 目录被添加。

git status

输出会显示：

On branch master
Changes to be committed:
 (use "git reset HEAD <file>..." to unstage)

 new file: .gitmodules
 new file: submodule_directory

.gitmodules 文件记录了子模块的信息，包括路径和 URL。查看其内容：

cat .gitmodules

输出类似：

[submodule "submodule_directory"]
 path = submodule_directory
 url = ../submodule_repo

submodule_directory 目录现在是 submodule_repo 的一个工作副本，但它处于一个特殊的“游离 HEAD”（detached HEAD）状态，指向添加子模块时 submodule_repo 的最新提交。

提交子模块的添加：

将 .gitmodules 文件和子模块目录的添加提交到主仓库：

git add .gitmodules submodule_directory
git commit -m "Add submodule_repo as a submodule"

现在，主仓库已经记录了子模块的存在以及它指向的特定提交。

2. 克隆包含子模块的仓库

当其他人克隆包含子模块的仓库时，默认情况下子模块目录是空的。需要额外的步骤来初始化和更新子模块。

假设你要克隆上面创建的 parent_repo。

正常克隆主仓库：
```
# 回到上一级目录
cd ..

# 克隆主仓库
git clone parent_repo cloned_parent_repo
```
进入克隆后的 cloned_parent_repo 目录，你会发现 submodule_directory 目录存在，但里面是空的：
```
cd cloned_parent_repo
ls submodule_directory
```
（没有输出或显示目录为空）

初始化并更新子模块：

需要运行以下命令来初始化子模块配置并拉取子模块的代码：
```
git submodule init
git submodule update
```
- git submodule init: 这个命令会读取 .gitmodules 文件，并将子模块的信息添加到主仓库的 .git/config 文件中。
- git submodule update: 这个命令会克隆子模块仓库到指定的路径，并检出 .gitmodules 文件中记录的特定提交。
运行 git submodule update 后，submodule_directory 目录就会包含子模块的代码了：
```
ls submodule_directory
```
输出：
```
submodule_file.txt
```

更便捷的克隆方式：

可以在克隆主仓库时直接使用 --recurse-submodules 选项，一步完成克隆、初始化和更新子模块：

# 回到上一级目录并删除之前克隆的仓库
cd ..
rm -rf cloned_parent_repo

# 使用 --recurse-submodules 选项克隆
git clone --recurse-submodules parent_repo cloned_parent_repo_recursive

# 进入目录并查看子模块内容
cd cloned_parent_repo_recursive
ls submodule_directory

输出：

submodule_file.txt

这种方式更推荐，因为它简化了克隆包含子模块的项目流程。

3. 更新子模块

子模块固定在主仓库记录的特定提交上。如果子模块仓库有了新的提交，你需要手动更新主仓库中对子模块的引用。

假设 submodule_repo 有了新的提交。

在子模块仓库中进行新的提交：

进入 submodule_repo 目录（或者克隆后的 cloned_parent_repo/submodule_directory 目录），进行修改并提交：

# 进入子模块目录 (如果你还在 parent_repo 或其克隆目录中)
cd submodule_directory # 或者 cd ../submodule_repo

# 创建或修改文件
echo "Adding new content to submodule." >> submodule_file.txt

# 添加并提交
git add .
git commit -m "Add new content to submodule"

# (如果子模块有远程仓库) 推送到子模块的远程仓库
# git push origin master

在主仓库中更新子模块引用：

回到主仓库（parent_repo 或其克隆目录）。此时，主仓库仍然指向子模块的旧提交。进入子模块目录之后运行 git status 会显示子模块目录已被修改：
```
cd .. # 回到主仓库目录 (parent_repo 或 cloned_parent_repo)
cd parent_repo
cd submodule_directory
git status
```
输出类似：
```
On branch master
Changes not staged for commit:
 (use "git add <file>..." to update what will be committed)
 (use "git checkout -- <file>..." to discard changes in working directory)

 modified: submodule_directory (new commits)

no changes added to commit (use "git add" and/or "git commit -a")
```
要将主仓库更新到子模块的最新提交，可以使用 git submodule update --remote 命令：
```
git submodule update --remote
```
这个命令会进入每个子模块目录，拉取最新的代码，并更新主仓库中子模块的引用到最新的提交。

注意： git submodule update --remote 默认会更新到子模块仓库当前分支的最新提交。如果你希望更新到特定分支，可以使用 --remote --merge <分支名> 或 --remote --rebase <分支名>。

更新后，再次运行 git status，你会看到子模块目录再次被标记为已修改，但这次是因为它的引用指向了新的提交：
```
git status
```
输出类似：
```
On branch master
Changes to be committed:
 (use "git reset HEAD <file>..." to unstage)

 modified: submodule_directory
```
提交主仓库的更新：

将主仓库中对子模块引用的更新进行提交：
```
git add submodule_directory # 当然直接git add . 也可以
git commit -m "Update submodule_directory to latest commit"

# (如果主仓库有远程仓库) 推送到主仓库的远程仓库
# git push origin master
```
这样，主仓库就记录了子模块的最新状态。

4. 在子模块中工作

在子模块目录中，你可以像在任何独立的 Git 仓库中一样进行操作：切换分支、创建提交、推拉代码等。

进入子模块目录：

cd submodule_directory

现在你就在 submodule_repo 的工作目录中了。你可以进行正常的 Git 操作：

# 查看当前分支
git branch

# 切换分支
# git checkout <分支名>

# 创建新的提交
# (修改文件，git add，git commit)

# 推送到子模块的远程仓库
# git push origin <分支名>

完成在子模块中的工作后，回到主仓库目录：

cd ..

如果子模块中有了新的提交，主仓库会检测到变化（如上面更新子模块的步骤所示），你需要再次在主仓库中提交对子模块引用的更新。

5. 切换分支（包含子模块）

在包含子模块的主仓库中切换分支可能会有些复杂，因为不同分支可能引用子模块的不同提交，甚至在某些分支上没有子模块。

当切换到一个新分支时，Git 会尝试根据新分支的 .gitmodules 文件和主仓库记录的子模块提交信息，自动更新子模块。

示例：切换到新分支

假设在 parent_repo 中创建一个新分支 feature_branch：

git checkout -b feature_branch

如果在 feature_branch 上对子模块进行了修改（例如，更新到新的提交），然后切换回 master 分支：

git checkout master

Git 会尽力将子模块恢复到 master 分支所指向的提交。如果出现问题（例如，子模块目录有未提交的修改），Git 可能会报错或将子模块目录标记为未追踪。

为了避免潜在的问题，建议在切换主仓库分支之前，确保子模块目录是干净的（没有未提交的修改）。如果子模块中有修改需要保留，先在子模块内部进行提交。

6. 删除子模块

删除子模块比添加子模块要麻烦一些，需要执行几个步骤来彻底移除子模块的记录和文件。

假设我们要从 parent_repo 中删除 submodule_directory 子模块。

取消初始化子模块：
```
git submodule deinit submodule_directory
```
这个命令会移除 .git/config 文件中关于该子模块的配置。
移除 .gitmodules 文件中的对应条目：

使用文本编辑器打开 .gitmodules 文件，删除对应子模块的配置段落（例如，[submodule "submodule_directory"] 开始的部分）。

或者使用命令：
```
git config -f .gitmodules --remove-section submodule.submodule_directory
```
从暂存区移除子模块：

子模块在 Git 中被记录为一个特殊的工作树条目。需要将其从暂存区移除：
```
git rm --cached submodule_directory
```
手动删除子模块的工作目录和 .git/modules 中的相关文件：
```
rm -rf submodule_directory
rm -rf .git/modules/submodule_directory
```
- rm -rf submodule_directory: 删除子模块在主仓库中的工作目录。
- rm -rf .git/modules/submodule_directory: 删除 Git 在主仓库内部为该子模块存储的元数据和对象。

提交删除操作：

git add .gitmodules
git commit -m "Remove submodule_directory submodule"

现在，子模块就彻底从主仓库中删除了。

总结常用命令

git submodule add <url> <path>: 添加子模块。
git submodule init: 初始化本地的子模块配置。
git submodule update: 克隆子模块仓库并检出主仓库指定的提交。
git clone --recurse-submodules <url>: 克隆主仓库并递归地初始化和更新子模块。
git submodule update --remote: 将子模块更新到其远程仓库的最新提交，并更新主仓库的引用。
git submodule deinit <path>: 取消初始化子模块。
git rm --cached <path>: 从暂存区移除子模块。

更高级的用法和注意事项

指定分支或标签： 添加子模块时，可以使用 -b <分支名> 或指定一个特定的提交 SHA1 来控制子模块的初始状态。
子模块的子模块： 如果子模块本身也包含子模块，在克隆和更新时需要使用 --recursive 选项，例如 git clone --recursive 和 git submodule update --recursive。
游离 HEAD 状态： 在子模块目录中进行修改并提交后，子模块会处于游离 HEAD 状态。如果你想在子模块中固定跟踪某个分支，需要在子模块目录中 git checkout <分支名>，然后在主仓库中提交对子模块引用的更新。
使用 .gitattributes 忽略子模块的某些文件： 可以在主仓库的 .gitattributes 文件中配置，以便 Git 在某些操作（如 git status）中忽略子模块目录中的未追踪或已修改文件。
替代方案： 对于简单的依赖管理，考虑使用包管理器（如 npm, yarn, pip, Composer, Maven, Gradle 等），它们通常比 Git Submodule 更易于管理依赖版本和更新。Git Submodule 更适合于包含独立的、需要独立开发和版本控制的子项目或库。

希望这份详细的教程能帮助你理解和使用 Git Submodule！如果在实践中遇到问题，可以根据具体的错误信息进行搜索或提问。

Docker使用实战-compose教程

Tue, 18 Mar 2025 15:48:18 +0800

#--------------------------------------
# 1. 通用/推荐的关闭方式 (任何系统)
#--------------------------------------

# 向 Redis 服务器发送关闭信号 (会安全保存数据)
# 这是最推荐的关闭方式
redis-cli shutdown

#--------------------------------------
# 直接运行 / Docker 容器内 (你当前的环境)
#--------------------------------------

# 启动 (前台运行，日志会占满终端)
redis-server

# 启动 (使用配置文件，推荐)
redis-server /path/to/redis.conf

# 启动 (后台运行，就像你之前用的)
redis-server &

# 关闭 (在 Docker 或直接运行时，用 cli 关闭)
redis-cli shutdown

# 强行关闭 (如果上面的命令无效)
# 1. 找到进程 PID
ps aux | grep redis-server
# 2. 杀死进程 (用 PID 替换 12345)
kill 12345



#--------------------------------------
# Linux (使用 systemd, 如 Ubuntu, CentOS)
#--------------------------------------

# 启动服务
sudo systemctl start redis-server
# (服务名也可能是 redis)
# sudo systemctl start redis

# 停止服务
sudo systemctl stop redis-server

# 重启服务
sudo systemctl restart redis-server

# 查看服务状态
sudo systemctl status redis-server

# 设置开机自启
sudo systemctl enable redis-server

下面是一个详细的 Docker Compose 教程，涵盖了从基础概念到实际操作的全面内容。教程将逐步讲解 Docker Compose 的用途、安装、配置文件编写以及常见使用场景，帮助你快速上手。

Docker Compose 起步教程

什么是 Docker Compose？

Docker Compose 是一个用于定义和运行多容器 Docker 应用的工具。它通过一个 YAML 文件（通常是 docker-compose.yml）来配置多个服务、网络和卷，然后使用单一命令启动和管理这些容器。相比手动运行 docker run，它更适合需要协调多个容器的复杂应用。

适用场景

开发环境：快速搭建包含前端、后端、数据库等的本地开发环境。
测试：运行集成测试或模拟生产环境。
小型部署：单机多容器应用的部署。

安装 Docker Compose

Docker Compose 有两种形式：

旧版（docker-compose）：一个独立的 Python 工具。
新版（docker compose）：集成在 Docker CLI 中的插件，从 Docker 20.10 开始默认包含。

检查是否已安装

运行以下命令：

docker compose version

如果输出类似 Docker Compose version v2.x.x，说明已安装新版。
如果提示未找到命令，尝试 docker-compose --version 检查旧版。

安装（如果需要）

Linux / macOS / Windows（新版）：如果你的 Docker 是最新版（20.10+），无需额外安装，直接用 docker compose。

旧版安装（可选）：

sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

前提条件

已安装 Docker Engine（运行 docker --version 确认）。

基本概念

服务（Services）：一个服务对应一个容器，可以基于镜像启动，定义端口、卷等。
网络（Networks）：Compose 默认创建网络，所有服务可以互相通信。
卷（Volumes）：用于持久化数据，防止容器删除后数据丢失。
docker-compose.yml：核心配置文件，描述整个应用。

创建第一个 Docker Compose 文件

假设我们要搭建一个简单的 Web 应用，包括：

一个 Nginx Web 服务器。
一个 Redis 数据库。

1. 创建项目目录

mkdir my-compose-app
cd my-compose-app

2. 编写 `docker-compose.yml`

创建一个名为 docker-compose.yml 的文件，内容如下：

version: '3.8' # 使用最新稳定的版本
services:
 web:
 image: nginx:latest  # 使用官方 Nginx 镜像
 ports:
 - "8080:80" # 主机端口 8080 映射到容器端口 80
 volumes:
 - ./html:/usr/share/nginx/html  # 挂载本地 html 文件夹
 redis:
 image: redis:latest  # 使用官方 Redis 镜像
 ports:
 - "6379:6379" # 映射 Redis 默认端口
 volumes:
 - redis-data:/data # 使用命名卷存储数据

volumes:
 redis-data: # 定义一个命名卷

文件解析

version: '3.8'：指定 Compose 文件格式版本。
services：定义两个服务：
- web：运行 Nginx，映射端口 8080:80，挂载本地 ./html 文件夹。
- redis：运行 Redis，映射端口 6379，数据存储在命名卷 redis-data。
volumes：定义一个命名卷 redis-data，用于持久化 Redis 数据。

3. 创建 HTML 文件（可选）

在项目目录下创建 html 文件夹，并添加一个简单的 index.html：

mkdir html
echo "<h1>Hello, Docker Compose!</h1>" > html/index.html

4. 启动应用

运行以下命令启动所有服务：

docker compose up -d

-d 表示后台运行。

5. 验证

检查运行中的容器：
```
docker compose ps
```
输出应显示 web 和 redis 服务状态为 Up。
访问 Nginx：打开浏览器，输入 http://localhost:8080，应看到 “Hello, Docker Compose!"。
检查 Redis：用 Redis 客户端连接 localhost:6379。

6. 停止和清理

停止服务并删除容器：

docker compose down

如果要删除卷数据：

docker compose down -v

常用配置字段

以下是 docker-compose.yml 中常用的字段：

服务配置

image：指定镜像（如 nginx:latest）。

build：构建镜像（替代 image），指定 Dockerfile 路径：

build:
 context: .  # 构建上下文路径
 dockerfile: Dockerfile  # Dockerfile 文件名

ports：端口映射，格式 "主机端口:容器端口"。

volumes：卷挂载，支持本地路径或命名卷：

volumes:
 - ./data:/app/data  # 本地路径
 - my-volume:/data  # 命名卷

environment：环境变量：

environment:
 - DEBUG=true
 - PORT=8080

depends_on：定义服务启动依赖：
```
depends_on:
 - redis
```

全局配置

networks：自定义网络：
```
networks:
 my-network:
 driver: bridge
```
volumes：定义命名卷：
```
volumes:
 my-volume:
```

进阶示例：WordPress + MySQL

以下是一个更复杂的例子，搭建 WordPress 和 MySQL：

`docker-compose.yml`

version: '3.8'
services:
 db:
 image: mysql:8.0
 volumes:
 - db-data:/var/lib/mysql
 environment:
 MYSQL_ROOT_PASSWORD: somewordpress
 MYSQL_DATABASE: wordpress
 MYSQL_USER: wordpress
 MYSQL_PASSWORD: wordpress
 restart: unless-stopped

 wordpress:
 image: wordpress:latest
 ports:
 - "8080:80"
 volumes:
 - wp-data:/var/www/html
 environment:
 WORDPRESS_DB_HOST: db
 WORDPRESS_DB_USER: wordpress
 WORDPRESS_DB_PASSWORD: wordpress
 WORDPRESS_DB_NAME: wordpress
 depends_on:
 - db
 restart: unless-stopped

volumes:
 db-data:
 wp-data:

启动

docker compose up -d

访问 http://localhost:8080，即可看到 WordPress 安装页面。

常用命令

启动服务：docker compose up -d
停止服务：docker compose stop
删除服务（保留卷）：docker compose down
查看日志：docker compose logs [服务名]
重启服务：docker compose restart
构建镜像：docker compose build
查看服务状态：docker compose ps

保存和迁移

保存镜像

提交容器为镜像：

docker commit my-compose-app_web_1 mywebimage:latest

导出镜像：

docker save -o myimages.tar mywebimage:latest

备份卷

docker run --rm -v my-compose-app_db-data:/data -v $(pwd):/backup busybox tar cvf /backup/db-backup.tar /data

恢复

加载镜像：
```
docker load -i myimages.tar
```

恢复卷：

docker run --rm -v my-compose-app_db-data:/data -v $(pwd):/backup busybox tar xvf /backup/db-backup.tar -C /data

启动：docker compose up -d

注意事项

版本选择：根据 Docker Engine 版本选择合适的 version（推荐 3.8 或更高）。
命名冲突：多个 Compose 项目运行时，卷和网络名称可能冲突，可用 docker compose -p 项目名 指定项目名。
最佳实践：尽量通过 build 和 Dockerfile 定义镜像，而不是手动修改容器。

Dokploy + Traefik 生产部署

背景

在 Dokploy 上使用 docker-compose.dokploy.yml 部署应用后，页面访问返回 404。这个 404 通常不是前端 Nginx 的 SPA fallback 返回的，因为前端容器内的 / 一般会 fallback 到 index.html。

更常见的原因是 Traefik 没有匹配到任何路由：

DOMAIN 没有被 Docker Compose 插值，生成了空的 Host(``)。
访问的域名不是 compose labels 里声明的 Host rule。
容器没有接入 Dokploy 的 Traefik 网络。
后端不健康，依赖后端健康状态的前端服务没有启动。

Dokploy 环境变量

在 Dokploy 的 Compose Environment 中必须配置：

DOMAIN=fsense.example.com

注意：

DOMAIN 只写域名，不要写 http://、https:// 或路径。
本地 .env.dokploy 不一定会被 Dokploy 自动加载。除非 Dokploy 的 compose 命令显式使用 --env-file .env.dokploy，否则要把变量复制到 Dokploy UI 的 Environment 中。
密钥、数据库地址、对象存储配置等也放在 Dokploy Environment，不要写入公开仓库。

DNS 记录

如果 compose 使用三套前端域名，需要把这些域名都解析到 Dokploy 服务器：

fsense.example.com
admin.fsense.example.com
addin.fsense.example.com

对应关系：

域名	服务
`https://${DOMAIN}`	`outlook-index`
`https://admin.${DOMAIN}`	`admin-frontend`
`https://addin.${DOMAIN}`	`outlook-addin`

Traefik labels 模板

主站前端示例：

labels:
 - "traefik.enable=true"
 - "traefik.docker.network=dokploy-network"
 - "traefik.http.middlewares.outlook-index-https-redirect.redirectscheme.scheme=https"
 - "traefik.http.routers.outlook-index-web.rule=Host(`${DOMAIN:?Set DOMAIN in Dokploy environment}`)"
 - "traefik.http.routers.outlook-index-web.entrypoints=web"
 - "traefik.http.routers.outlook-index-web.middlewares=outlook-index-https-redirect"
 - "traefik.http.routers.outlook-index.rule=Host(`${DOMAIN:?Set DOMAIN in Dokploy environment}`)"
 - "traefik.http.routers.outlook-index.entrypoints=websecure"
 - "traefik.http.routers.outlook-index.tls=true"
 - "traefik.http.routers.outlook-index.tls.certresolver=letsencrypt"
 - "traefik.http.services.outlook-index.loadbalancer.server.port=80"

管理后台示例：

labels:
 - "traefik.enable=true"
 - "traefik.docker.network=dokploy-network"
 - "traefik.http.middlewares.admin-frontend-https-redirect.redirectscheme.scheme=https"
 - "traefik.http.routers.admin-frontend-web.rule=Host(`admin.${DOMAIN:?Set DOMAIN in Dokploy environment}`)"
 - "traefik.http.routers.admin-frontend-web.entrypoints=web"
 - "traefik.http.routers.admin-frontend-web.middlewares=admin-frontend-https-redirect"
 - "traefik.http.routers.admin-frontend.rule=Host(`admin.${DOMAIN:?Set DOMAIN in Dokploy environment}`)"
 - "traefik.http.routers.admin-frontend.entrypoints=websecure"
 - "traefik.http.routers.admin-frontend.tls=true"
 - "traefik.http.routers.admin-frontend.tls.certresolver=letsencrypt"
 - "traefik.http.services.admin-frontend.loadbalancer.server.port=80"

Outlook add-in 示例：

environment:
 - OUTLOOK_ADDIN_HOST_URL=https://addin.${DOMAIN:?Set DOMAIN in Dokploy environment}
labels:
 - "traefik.enable=true"
 - "traefik.docker.network=dokploy-network"
 - "traefik.http.middlewares.outlook-addin-https-redirect.redirectscheme.scheme=https"
 - "traefik.http.routers.outlook-addin-web.rule=Host(`addin.${DOMAIN:?Set DOMAIN in Dokploy environment}`)"
 - "traefik.http.routers.outlook-addin-web.entrypoints=web"
 - "traefik.http.routers.outlook-addin-web.middlewares=outlook-addin-https-redirect"
 - "traefik.http.routers.outlook-addin.rule=Host(`addin.${DOMAIN:?Set DOMAIN in Dokploy environment}`)"
 - "traefik.http.routers.outlook-addin.entrypoints=websecure"
 - "traefik.http.routers.outlook-addin.tls=true"
 - "traefik.http.routers.outlook-addin.tls.certresolver=letsencrypt"
 - "traefik.http.services.outlook-addin.loadbalancer.server.port=80"

关键点：

${DOMAIN:?Set DOMAIN in Dokploy environment} 可以让 compose 在变量缺失时直接失败，避免部署出空 Host rule。
traefik.docker.network=dokploy-network 明确告诉 Traefik 走 Dokploy 网络。
web 路由负责 HTTP 入口，并通过 middleware 跳到 HTTPS。
websecure 路由负责 HTTPS 入口和证书。

网络配置

服务需要接入 Dokploy 的外部网络：

networks:
 dokploy-network:
 external: true

每个需要被 Traefik 或反向代理访问的服务都要加入该网络：

networks:
 - dokploy-network

如果服务不需要公网访问，例如内部 backend，可以只 expose 端口，不直接挂 Traefik label。

只重建后端导致前端 API 代理失效

Dokploy / Docker Compose 部署时可能只重建发生变更的服务。例如后端代码变化后，只重建 backend，而 frontend 容器没有重启。

这种情况下可能出现一个隐蔽问题：

frontend 里的 Nginx 启动时解析过 backend:8000。
后端容器重建后，Docker 内部 IP 发生变化。
前端容器没有重启，Nginx 仍然可能持有旧的 upstream 解析结果。
页面本身还能打开，但 /api/* 代理到后端失败，看起来像"前端路由"或"接口路由"坏了。

推荐做法是让 Nginx 使用 Docker 内置 DNS，并定期重解析后端服务名：

resolver 127.0.0.11 ipv6=off valid=5s;

location /api/ {
 set $backend_upstream backend:8000;

 rewrite ^/api/?(.*)$ /$1 break;
 proxy_pass http://$backend_upstream;
 proxy_http_version 1.1;
 proxy_set_header Host $host;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
}

注意：proxy_pass 一旦使用变量，就不要再写成 proxy_pass http://$backend_upstream/;。带变量的 proxy_pass 不再沿用普通 proxy_pass http://backend:8000/; 的 URI 替换语义，尾部 / 很容易把请求错误地转发到根路径。

这个问题和 Traefik Host rule 404 不是同一个层面：

Traefik Host rule 错误：请求进不了前端容器，通常直接 404。
Nginx backend DNS 过期：请求能进前端容器，但 /api/* 代理后端失败。

macOS Docker build 使用 Clash 代理

在 macOS + Docker Desktop + Clash 环境里，docker compose build 和宿主机终端不是同一个网络视角。宿主机里的 127.0.0.1 是 Mac 自己，但 Docker build 容器里的 127.0.0.1 是构建容器本身。

一个典型现象是前端镜像构建时报平台原生依赖缺失，例如：

Error: Cannot find module '../lightningcss.linux-arm64-musl.node'

如果日志里 RUN npm ci 显示为 CACHED，说明这次构建没有重新安装依赖。缓存层里可能缺了 Alpine / Linux / arm64 需要的 optional native package，例如 lightningcss-linux-arm64-musl。这类问题看起来像 Node 包损坏，本质上经常是“旧 Docker build 缓存层 + 网络代理不稳定”共同导致的。

先强制绕过缓存验证真实问题：

docker compose build --no-cache kimi-ppt-frontend

如果错误变成 npm ERR! code ECONNRESET，就说明重新拉包时 Docker build 到 npm registry 的链路不稳定。

检查当前 shell 代理：

printenv | grep -i proxy

检查 ~/.zshrc 是否有重复覆盖：

grep -nE 'proxy|Proxy|Clash|789[0-9]' ~/.zshrc

容易出现的错误配置是前面写了一个可用端口，后面又覆盖成另一个端口：

export http_proxy="http://127.0.0.1:7897"
export https_proxy="http://127.0.0.1:7897"
export ALL_PROXY="socks5://127.0.0.1:7897"

# 后面又覆盖了 http_proxy / https_proxy
export https_proxy=http://127.0.0.1:7899 http_proxy=http://127.0.0.1:7899

应该保留一套一致配置。普通宿主机命令可以继续使用 127.0.0.1：

export http_proxy="http://127.0.0.1:7897"
export https_proxy="http://127.0.0.1:7897"
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$https_proxy"
export ALL_PROXY="socks5://127.0.0.1:7897"
export all_proxy="$ALL_PROXY"
export NO_PROXY="127.0.0.1,localhost,::1,host.docker.internal,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12"
export no_proxy="$NO_PROXY"

但 Docker build 里要把代理地址改成宿主机网关：

docker compose build --no-cache \
 --build-arg HTTP_PROXY=http://host.docker.internal:7897 \
 --build-arg HTTPS_PROXY=http://host.docker.internal:7897 \
 kimi-ppt-frontend

如果前端镜像已经重新构建成功，再构建整套服务：

docker compose build
docker compose up -d

验证入口：

curl -I http://localhost/
curl http://localhost:8000/health

如果 http://localhost/ 返回 200 OK，/health 返回类似 {"status":"ok"}，说明前端和后端容器都已经正常启动。

注意：不要把完整 ~/.zshrc 粘贴到公开位置。很多人会把 API key、token 和代理配置都放在同一个 shell 配置文件里。

404 排查命令

在服务器或 Dokploy 构建环境中检查最终插值结果：

docker compose -f docker-compose.dokploy.yml config | grep 'Host'

正常情况下应该看到实际域名，例如：

Host(`fsense.example.com`)
Host(`admin.fsense.example.com`)
Host(`addin.fsense.example.com`)

检查容器是否运行：

docker ps | grep app-

检查后端健康和启动日志：

docker logs app-backend --tail=100

如果后端不健康，依赖 condition: service_healthy 的前端服务可能不会启动，Traefik 也就没有可用服务。

修复检查清单

Dokploy Environment 中已设置 DOMAIN，且值不包含协议和路径。
DNS 已解析 ${DOMAIN}、admin.${DOMAIN}、addin.${DOMAIN}。
compose labels 中有 traefik.docker.network=dokploy-network。
HTTPS router 使用 entrypoints=websecure、tls=true、tls.certresolver=letsencrypt。
HTTP router 使用 entrypoints=web 并绑定 HTTPS redirect middleware。
docker compose config 输出的 Host rule 是实际域名，不是空字符串。
backend 健康检查通过，前端容器正常启动。
如果只重建过 backend 后 /api/* 失效，检查前端 Nginx 是否使用 Docker DNS 运行时重解析。

docker使用教程

Tue, 18 Mar 2025 09:57:06 +0800

docker容器常用命令
Docker使用技巧
docker实战

常用命令

docker 单机常用命令

# 列出所有正在运行的容器
docker ps [-a]

# 停止并删除容器
docker stop <容器ID或容器名>
docker rm <容器ID或容器名>


# 删除指定卷
docker volume rm <卷ID或卷名>

# 查看所有容器的统计信息, --no-stream 不实时更新
docker stats [容器ID或容器名] [--no-stream]

# 清理所有停止的容器
docker rm $(docker ps -aq)
# 清理所有悬空的镜像
docker rmi $(docker images -qf "dangling=true")
# 清理所有悬空的网络
docker network prune $(docker network ls -qf "dangling=true")
# 清理所有悬空的卷
docker volume prune $(docker volume ls -qf "dangling=true")

# 将容器的当前状态保存为新的镜像
docker commit <my-container> <my-new-image> [:tag] # 如果tag不填就默认是latest

docker swarm 常用命令

# 查看容器日志
docker logs -f <容器ID或容器名>

# 初始化 Swarm 集群（管理节点）
docker swarm init --advertise-addr <IP地址>

# 获取管理节点加入命令 
docker swarm join-token manager

# 获取加入集群的命令（在工作节点执行）
docker swarm join-token worker

# 加入 Swarm 集群
docker swarm join --token <token> --advertise-addr <IP地址> --data-path-addr <IP地址> --listen-addr 0.0.0.0:2377 <管理节点IP>:2377

# 离开 Swarm 集群
docker swarm leave

# 强制离开集群
docker swarm leave --force

# 更新 Swarm 配置
docker swarm update --param value

# 查看集群节点列表
docker node ls

# 查看节点详细信息
docker node inspect <节点ID或名称>

# 更新节点属性
docker node update --availability active/pause/drain <节点ID>

# 提升节点为管理节点
docker node promote <节点ID>

# 降级管理节点为工作节点
docker node demote <节点ID>

# 删除节点
docker node rm <节点ID>

# 创建服务
docker service create --name <服务名> --replicas <副本数> -p <端口> <镜像名>

# 查看服务列表
docker service ls

# 查看服务详细信息
docker service inspect <服务名>

# 查看服务运行的任务
docker service ps <服务名>

# 扩展服务副本数
docker service scale <服务名>=<副本数>

# 更新服务配置
docker service update --image <新镜像> <服务名>

# 更新服务端口
docker service update --publish-add <端口> <服务名>

# 删除服务
docker service rm <服务名>

# 查看服务日志
docker service logs <服务名>


# 创建覆盖网络
docker network create --driver overlay <网络名>

# 查看网络列表
docker network ls

镜像 (Image) 相关命令

镜像是创建容器的基础，包含了应用程序及其依赖的环境。

命令	描述
`docker images`	列出本地所有镜像。
`docker pull [镜像名]:[标签]`	从 Docker Hub 或其他镜像仓库拉取镜像 (例如: `docker pull ubuntu:22.04`)。
`docker push [用户名]/[镜像名]:[标签]`	将本地镜像推送到 Docker Hub 或其他镜像仓库。
`docker build -t [镜像名]:[标签] .`	根据当前目录下的 Dockerfile 构建镜像 (例如: `docker build -t my-app:1.0 .`)。
`docker rmi [镜像ID或镜像名]`	删除一个或多个镜像 (例如: `docker rmi ubuntu:22.04`)。
`docker tag [源镜像] [新镜像名]`	为本地镜像添加一个新的标签 (例如: `docker tag my-app:1.0 my-app:latest`)。
`docker history [镜像名]`	查看镜像的构建历史。
`docker save -o [文件名.tar] [镜像名]`	将镜像保存为一个 tar 归档文件。
`docker load -i [文件名.tar]`	从一个 tar 归档文件加载镜像。
`docker rmi $(docker images -qf "dangling=true")`	删除所有悬空的（dangling）镜像。

容器 (Container) 相关命令

容器是镜像的运行实例，是真正运行应用程序的地方。

命令	描述
`docker run [选项] [镜像名] [命令]`	创建并启动一个新的容器。
`docker ps`	列出所有正在运行的容器。
`docker ps -a`	列出所有容器（包括已停止的）。
`docker start [容器ID或容器名]`	启动一个或多个已停止的容器。
`docker stop [容器ID或容器名]`	停止一个或多个正在运行的容器。
`docker restart [容器ID或容器名]`	重启一个容器。
`docker rm [容器ID或容器名]`	删除一个或多个容器。
`docker rm -f $(docker ps -aq)`	强制删除所有容器（无论运行中还是已停止）。
`docker logs [容器ID或容器名]`	查看容器的日志输出 (`-f` 选项可以持续跟踪日志)。
`docker exec -it [容器ID] [命令]`	在正在运行的容器中执行一个交互式命令 (例如: `docker exec -it my-nginx /bin/bash`)。
`docker cp [本地路径] [容器ID]:[容器内路径]`	在宿主机和容器之间复制文件/文件夹。
`docker stats`	实时显示容器的资源使用情况。
`docker top [容器ID]`	查看容器内运行的进程。
`docker inspect [容器ID或镜像ID]`	查看容器或镜像的详细信息（元数据）。

`docker run` 常用选项

-d: 后台运行容器（detached mode）。
-p [宿主机端口]:[容器端口]: 端口映射。
-v [宿主机路径]:[容器内路径]: 数据卷挂载。
--name [容器名]: 为容器指定一个名称。
-it: 启动交互式会话 (-i 交互, -t 分配一个伪终端)。
--rm: 容器停止后自动删除。
-e [环境变量名]=[值]: 设置环境变量。
--network [网络名]: 将容器连接到指定网络。

示例: docker run -d -p 8080:80 --name my-web-server -v /webapp:/usr/share/nginx/html nginx

Docker Compose 相关命令

用于定义和运行多容器 Docker 应用程序的工具。

命令	描述
`docker-compose up`	根据 `docker-compose.yml` 创建并启动所有服务。
`docker-compose up -d`	在后台创建并启动所有服务。
`docker-compose down`	停止并移除由 `up` 创建的容器、网络、卷。
`docker-compose ps`	列出 `docker-compose.yml` 文件中定义的所有容器的状态。
`docker-compose logs`	查看所有服务的日志。
`docker-compose logs -f [服务名]`	实时跟踪特定服务的日志。
`docker-compose build`	构建或重新构建服务。
`docker-compose pull`	拉取服务依赖的镜像。
`docker-compose exec [服务名] [命令]`	在指定的服务容器中执行命令。
`docker-compose stop`	停止服务，但不删除容器。
`docker-compose start`	启动已停止的服务。

系统与资源管理命令

命令	描述
`docker system prune`	清理系统中未使用的 Docker 资源（容器、镜像、网络、卷）。
`docker system prune -a --volumes`	更彻底的清理，会删除所有未使用的镜像和数据卷。请谨慎使用！
`docker system df`	查看 Docker 的磁盘使用情况。
`docker volume ls`	列出所有的数据卷。
`docker volume rm [卷名]`	删除一个或多个数据卷。
`docker network ls`	列出所有的网络。
`docker network rm [网络名]`	删除一个或多个网络。
`docker login`	登录到 Docker Hub 或其他镜像仓库。
`docker logout`	登出 Docker Hub 或其他镜像仓库。
`docker info`	显示 Docker 系统范围的信息。
`docker version`	显示 Docker 的版本信息。

docker 安装

阿里云安装docker

阿里云服务器


# 先下载 GPGkey
sudo curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc


# Add the Aliyun Repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Update your Package List
sudo apt-get update

# Install Docker 
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin



#配置镜像加速
sudo mkdir -p /etc/docker

sudo tee /etc/docker/daemon.json <<-'EOF'
{
 "registry-mirrors": ["https://docker.m.daocloud.io","https://<你的加速镜像地址，进入阿里云镜像加速服务获取>.mirror.aliyuncs.com","https://mirror.ccs.tencentyun.com"]

}
EOF

#设置docker服务自启
sudo systemctl daemon-reload
sudo systemctl enable --now docker
sudo systemctl enable containerd


# verify the installation
docker version
docker compose version

#------------------------------------------
# 到这里docker到安装完成，下面是docker swarm的安装
#------------------------------------------

# 初始化docker swarm 集群 --advertise-addr <ip地址> #如果没有指定，默认是当前机器的局域网ip地址
docker swarm init --advertise-addr <公网ip地址>

腾讯云安装docker

腾讯云服务器

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL http://mirrors.tencentyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] http://mirrors.tencentyun.com/docker-ce/linux/ubuntu \
 $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin


sudo mkdir -p /etc/docker

sudo tee /etc/docker/daemon.json <<-'EOF'
{
 "registry-mirrors": ["https://mirror.ccs.tencentyun.com"]
}
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

sudo systemctl enable --now docker
sudo systemctl enable containerd

windows 安装docker desktop

如果需要查询vpm有没有在容器里面生效

注意事项

使用指南

docker自动创建的数据卷自动挂载到 /mnt

在很多场景下，我们习惯让 Docker 自己管理数据卷（即 Named Volumes，比如 docker volume create my_vol）。这些卷默认存放在 /var/lib/docker/volumes/。

如果你想让 Docker 把这些自己创建的卷也放到 /mnt 里，这里有三种方案，请根据实际需求选择：

方案 A：修改全局默认存储路径（强烈推荐，一劳永逸）

这是最规范的做法。它不仅会把数据卷存到 /mnt，还会把拉取的镜像、容器日志等所有 Docker 数据都转移过去，彻底解放系统盘。

操作步骤：

停止 Docker 服务：

sudo systemctl stop docker

#如果docker.socket服务没有停止，需要先停止它
sudo systemctl stop docker.socket

修改或创建配置文件： 编辑 /etc/docker/daemon.json 文件：
```
sudo nano /etc/docker/daemon.json
```
写入以下配置（假设你要把数据存在 /mnt/docker_data）：
```
{
 "data-root": "/mnt/docker_data"
}
```
（重要）迁移历史数据： 为了防止你以前创建的容器和镜像丢失，务必将原数据同步到新目录：
```
sudo rsync -aP /var/lib/docker/ /mnt/docker_data/
```
重启 Docker：
```
sudo systemctl start docker
```

效果： 以后你执行任何关于 Docker 的操作，数据都会自动落在大硬盘 /mnt/docker_data 里了！

方案 B：使用软链接（简单粗暴）

如果你只想把数据卷（Volumes）挪到 /mnt，而镜像等其他数据还要留在系统盘，可以使用 Linux 的软链接魔法。

操作步骤：

停止服务：sudo systemctl stop docker
在 /mnt 创建目标文件夹：sudo mkdir -p /mnt/docker_volumes
迁移现有的卷数据：sudo mv /var/lib/docker/volumes/* /mnt/docker_volumes/
删除原本的空文件夹：sudo rm -rf /var/lib/docker/volumes

创建软链接：

sudo ln -s /mnt/docker_volumes /var/lib/docker/volumes

重启服务：sudo systemctl start docker

效果： 欺骗了 Docker。Docker 以为自己还是写在 /var/lib 下，但实际上数据已经悄悄存进了 /mnt。

方案 C：在 Docker Compose 中按需指定物理路径（优雅灵活）

如果你不想修改系统的任何配置，只想在部署某个特定项目时，让它自己的数据卷落在 /mnt，可以在定义 volume 时使用 local 驱动。

这在编写 docker-compose.yml 时非常实用：

version: '3.8'
services:
 db:
 image: mysql:8.0
 volumes:
 - mysql_data:/var/lib/mysql

volumes:
 mysql_data:
 driver: local
 driver_opts:
 type: none
 o: bind
 device: /mnt/my_project/mysql_data

效果： 既保留了 Named Volumes 的便捷性，又实现了数据的物理分离，非常适合项目迁移和备份。

总结建议

如果你的系统盘马上就要满了：别犹豫，直接用 方案 A，修改 data-root 把整个 Docker 搬家到大硬盘。
如果你只是想把项目数据单独分类存放大盘：推荐 方案 C，在 docker-compose.yml 中使用 driver_opts，干净且优雅。

希望这篇文章能帮你解决 Docker 存储空间的烦恼！如果遇到权限问题（Permission Denied），记得检查 /mnt 对应目录的用户权限哦（chown）。

(Tags: Docker, Linux, 运维，存储优化，DockerVolume)

简单开始一个docker镜像的使用

1. 拉取镜像

docker pull ubuntu

2.查看镜像是否拉取成功

docker images

3. 运行容器

docker run -itd --name <容器名称> -p <主机端口>:<容器端口> --cpus=30 ubuntu
# -p设置端口 --cpus/-c 设置核心

4. 通过 exec 命令进入 ubuntu 容器

docker exec -it <容器名> /bin/bash

5. 安装ssh

apt-get update

apt-get install openssh-client -y
apt-get install openssh-server -y

6. 安装vim

apt-get install vim -y

7. 安装conda

https://zhuanlan.zhihu.com/p/307923089 注意，可能要手动配置环境变量

8. 安装zip、unzip

apt-get install zip
apt-get install unzip

9. 解决中文乱码问题

export LC_ALL="C.UTF-8"
source /etc/bash.bashrc

10. 安装sudo

apt-get install sudo

Docker使用实战-MySQL和Ubuntu容器

1. 安装docker mysql容器

首先拉取mysql镜像，默认拉取最新版

docker pull mysql

然后创建容器

docker run --name mysql_zata -p 3306:3306 -e MYSQL_ROOT_PASSWORD=123456 mysql #第一个端口是主机的端口
或
docker run --name mysql_zata -p 53306:3306 -e MYSQL_ROOT_PASSWORD=123456 mysql

参数	解释
docker run:	创建Docker容器的命令。
–name mysql_zata	这个选项用于指定容器的名称，这里将容器命名为"mysql_zata"。
-p 3306:3306: [第一个3306是主机的端口可以改成其他的，第二个3306是容器的端口，也就是要固定的]可以改成如： -p 53306：3306
这个选项用于将容器内部的端口映射到宿主机上。具体来说，-p 3306:3306 将容器内部的MySQL数据库服务的端口3306映射到宿主机的端口3306。这样，您可以通过宿主机上的3306端口访问容器内的MySQL服务。
-e MYSQL_ROOT_PASSWORD=123456:	这个选项用于设置MySQL数据库的root用户的密码。在这里，密码被设置为"123456"。这是一个环境变量设置，MySQL容器会使用这个密码来授权root用户访问数据库。
mysql:	这是要运行的Docker镜像的名称。在这里，它是MySQL镜像，意味着会启动一个MySQL数据库容器。

现在是前台模式创建的（我也不是很清楚，反正关闭这个窗口服务就会停掉），关闭窗口也没事，可以重新再windows的docker界面重开

2. 安装Ubuntu容器并配置

1. 拉取镜像

docker pull ubuntu

2.查看镜像是否拉取成功

docker images

3. 运行容器

docker run -itd --name <容器名称> -p <主机端口>:<容器端口> ubuntu

4. 通过 exec 命令进入 ubuntu 容器

docker exec -it <容器名> /bin/bash

5. 安装ssh并启动

apt-get updata

apt-get install openssh-client
apt-get install openssh-server

# 启动
sudo service ssh start

6. 安装vim

apt-get install vim

7. 安装conda

https://zhuanlan.zhihu.com/p/307923089

注意，可能要手动配置环境变量（如果能直接用也就不用配置）

8. 安装zip、unzip

apt-get install zip
apt-get install unzip

9. 解决中文乱码问题

export LC_ALL="C.UTF-8"
source /etc/bash.bashrc

10. 安装sudo

apt-get install sudo

Docker使用技巧

docker的卷挂载功能

docker run -v <host_path>:<container_path> <image_name>

# 需要为每一个路径都添加-v
docker run -v <host_path1>:<container_path1> -v <host_path2>:<container_path2> ... <image_name>

windows环境下面的特殊情况（路径反斜杠）示例：假设你想将 Windows 上的 C:\data 映射到容器内的 /app/data

docker run -v /c/data:/app/data -it <image_name> /bin/bash


# 如果路径存在空格，需要用""包起来 如
docker run -v "/c/Program Files/my folder:/app" -it <image_name>

将镜像推送到远程仓库

推送到公开

docker login
docker tag my-app:1.0 myusername/my-app:1.0
docker push myusername/my-app:1.0

到私有

docker login registry.example.com # 如果是docker hub 只需要 login in
docker tag my-app:1.0 registry.example.com/myusername/my-app:1.0 # 重命名tag
docker push registry.example.com/myusername/my-app:1.0

Docker Context 教程

什么是 Docker Context？

在深入了解之前，我们首先需要理解 Docker Context 的概念。简单来说，Docker Context 是 Docker CLI（命令行工具）用来连接和管理不同 Docker 守护进程（Docker daemon）或 Kubernetes 集群的配置集合。

在 Docker CLI 的早期版本中，我们通常使用 DOCKER_HOST 环境变量来指定要连接的远程 Docker daemon。这种方式虽然有效，但对于需要频繁切换不同环境（例如：本地开发、远程测试服务器、生产环境等）的开发者来说，管理起来非常不便，因为它要求每次切换时都手动更改环境变量。

Docker Context 解决了这个问题。它允许你将连接信息（如主机地址、证书等）保存为一个命名的配置，并可以通过简单的命令 (docker context use) 在这些配置之间快速切换，而无需手动管理环境变量。

一个 Docker Context 可以包含：

Docker Endpoint：Docker 守护进程的地址（例如：tcp://<host>:<port> 或 ssh://<user>@<host>）。
Kubernetes Endpoint：Kubernetes API 服务器的地址。
安全认证信息：用于连接的证书和密钥。

默认情况下，当你安装 Docker 后，会自动创建一个名为 default 的上下文，它指向你本地的 Docker 守护进程。

为什么使用 Docker Context？

简化工作流：无需频繁设置和取消 DOCKER_HOST 环境变量。
集中管理：将所有不同环境的连接配置集中管理。
支持多种环境：不仅支持远程 Docker daemon，还支持连接到 Kubernetes 集群。
安全：可以方便地管理和切换不同环境的安全认证信息。

Docker Context 常用命令

在使用 Docker Context 之前，您需要确保您的 Docker 版本在 19.03 或更高。

1. 查看现有上下文

docker context ls 命令用于列出所有已定义的上下文。

docker context ls

您将看到类似以下的输出：

NAME DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR
default * Current DOCKER_HOST based configuration unix:///var/run/docker.sock swarm

NAME：上下文的名称。
*：星号表示当前正在使用的上下文。
DESCRIPTION：对上下文的描述。
DOCKER ENDPOINT：Docker 守护进程的连接地址。
KUBERNETES ENDPOINT：如果上下文用于 Kubernetes，则显示其连接地址。

2. 创建新上下文

docker context create 命令用于创建一个新的上下文。

创建连接到远程 Docker daemon 的上下文

有几种方式可以连接远程 Docker daemon，最常见的是通过 SSH 或 TCP。

a) 通过 SSH 连接

这是最推荐和最安全的连接方式。您需要确保：

本地机器已配置好无密码 SSH 登录远程主机。
远程主机上已安装 Docker，且当前用户有权限执行 docker 命令（通常通过将用户添加到 docker 用户组来实现）。

docker context create <context_name> --description "<description>" --docker "host=ssh://<username>@<remote_host>"

示例：

假设您的远程主机 IP 为 192.168.1.100，用户名为 ubuntu。

docker context create remote-server --description "Remote Docker daemon on dev server" --docker "host=ssh://ubuntu@192.168.1.100"

b) 通过 TCP 连接

这种方式需要远程 Docker daemon 暴露在 TCP 端口上，并且通常需要TLS加密来保证安全。

警告：不建议在没有TLS加密的情况下通过公共网络连接。

# 假设远程 Docker daemon 暴露在 2375 端口
docker context create remote-tcp --description "Insecure remote connection" --docker "host=tcp://192.168.1.100:2375"

# 如果使用 TLS 加密
docker context create remote-tls --description "Secure remote connection" --docker "host=tcp://192.168.1.100:2376" --tls-ca-path <path_to_ca> --tls-cert-path <path_to_cert> --tls-key-path <path_to_key>

c) 创建连接到 Kubernetes 集群的上下文

如果您已经使用 kubectl 配置了集群连接，Docker Context 可以自动从您的 .kube/config 文件中加载这些配置。

docker context create <context_name> --description "<description>" --kubernetes "config-file=<path_to_kubeconfig>" --kubernetes "context=<kube_context_name>"

示例：

docker context create k8s-cluster --description "My Kubernetes cluster" --kubernetes "context=my-cluster-context"

3. 切换上下文

docker context use 命令用于切换当前活动的上下文。

docker context use <context_name>

示例：

# 切换到之前创建的远程服务器上下文
docker context use remote-server

# 验证当前上下文
docker context ls

此时，docker context ls 的输出会显示 remote-server 旁边有星号 *。从现在开始，您所有的 docker 命令（例如 docker ps、docker images 等）都将在远程主机上执行。

4. 在单次命令中使用特定上下文

如果您只想在某一次命令中使用某个上下文，而不想永久切换，可以使用 --context 全局选项。

docker --context <context_name> <docker_command>

示例：

# 在不切换当前上下文的情况下，查看远程服务器上的容器列表
docker --context remote-server ps -a

5. 检查上下文详情

docker context inspect 命令可以查看某个上下文的详细配置信息。

docker context inspect <context_name>

示例：

docker context inspect remote-server

6. 更新上下文

docker context update 命令可以修改现有上下文的配置。

docker context update <context_name> --description "New description" --docker "host=..."

7. 移除上下文

docker context rm 命令可以删除一个上下文。

docker context rm <context_name>

综合示例：从本地切换到远程，再切换回来

这是一个完整的流程，展示了如何利用 Docker Context 简化日常工作。

步骤 1：检查本地默认上下文

# 检查默认上下文，确保指向本地
docker context ls

输出应显示 default *。

步骤 2：创建远程上下文

假设您要连接到 IP 为 192.168.1.100 的远程服务器。

docker context create my-remote-host --description "My development server" --docker "host=ssh://user@192.168.1.100"

步骤 3：切换到远程上下文

docker context use my-remote-host

此时，您已成功切换到远程环境。

步骤 4：在远程主机上执行命令

现在，您可以像操作本地 Docker 一样操作远程 Docker。

# 查看远程主机上正在运行的容器
docker ps

# 在远程主机上拉取一个镜像
docker pull nginx

# 在远程主机上运行一个新容器
docker run -d --name my-nginx -p 80:80 nginx

这些命令的执行都将在 192.168.1.100 上完成。

步骤 5：切换回本地上下文

当您完成远程操作后，可以轻松切换回本地环境。

docker context use default

步骤 6：验证切换

docker context ls

输出应再次显示 default *。

现在，您的 docker 命令又将作用于本地机器。

通过这个简单的教程，您可以看到 Docker Context 如何极大地简化了多 Docker 环境的管理，使其成为一个高效且安全的工具。

在 Windows 上实现 Docker in Docker (DinD) 终极教程

在 Windows 环境下开发时，我们有时会遇到需要在 Docker 容器内部再次调用 Docker 命令的场景，例如在 Jenkins CI/CD 流水线中构建 Docker 镜像。这个技术通常被称为 “Docker in Docker” (DinD)。

本文将详细介绍在 Windows (通过 Docker Desktop + WSL 2) 中实现 DinD 的两种主流方法，分析其优劣，并提供手把手的操作步骤。

核心概念：两种实现方式

挂载 Docker Socket (DooD - Docker-out-of-Docker): (官方推荐) 让容器内的 Docker CLI 直接与宿主机的 Docker 守护进程 (Daemon) 通信。这好比在办公室里装一部电话分机，直接使用公司总机的功能。
真正的 Docker-in-Docker (DinD): 在容器内运行一个全新的、完全隔离的 Docker 守护进程。这好比在办公室里私建一个小基站，内外通信完全独立。

结论先行：哪种方法最适合你？

对于绝大多数场景，方法一 (挂载 Docker Socket) 是最佳选择。

特性	方法一 (挂载 Socket)	方法二 (真·DinD)
推荐度	⭐⭐⭐⭐⭐ (强烈推荐)	⭐⭐ (仅特定场景)
隔离性	弱	强
安全性	较高 (无需特权模式)	低 (必须使用 `--privileged`)
性能/资源	开销极小	开销大 (双倍守护进程)
配置复杂度	简单	复杂
镜像缓存	与宿主机共享	独立缓存，占用额外空间
典型用例	CI/CD, 开发环境	隔离的 Docker 功能测试

方法一：挂载 Docker Socket (DooD) - 官方推荐

这是最简单、高效且安全的方式。

✨ 原理

通过 -v 参数将宿主机的 Docker Socket 文件 (/var/run/docker.sock) 挂载到容器内部。容器内的任何 docker 命令都会通过这个 Socket 文件被发送到宿主机，由宿主机的 Docker Daemon 执行。

✅ 优点

配置简单：一行命令参数即可搞定。
资源高效：无需启动额外的 Docker 服务，内存和 CPU 占用极低。
镜像共享：容器内拉取的镜像，宿主机可以直接使用，避免重复下载，节约时间和磁盘空间。

🚀 操作步骤

1. 前提条件

Windows 10/11 已安装 Docker Desktop。
Docker Desktop 使用 WSL 2 后端 (当前默认设置)。
- 检查方法: 打开 Docker Desktop > Settings > General，确保 Use the WSL 2 based engine 已勾选。

2. 运行容器并挂载 Socket

打开 PowerShell 或 CMD，执行以下命令来启动一个带有 Docker CLI 的容器：

docker run -it --rm \
 -v /var/run/docker.sock:/var/run/docker.sock \
 docker:latest \
 sh

命令解析:

docker run -it --rm: 以交互模式启动一个临时容器，退出后自动删除。
-v /var/run/docker.sock:/var/run/docker.sock: 核心命令。将宿主机的 Docker Socket 文件挂载到容器内的相同路径。

提示: 即使在 Windows 系统，也请直接使用 /var/run/docker.sock 这个 Linux 路径。Docker Desktop 会自动处理好与 WSL 2 之间的路径转换。
docker:latest: 使用官方 docker 镜像，它内置了 Docker 命令行工具 (CLI)。
sh: 启动容器内的 shell 环境。

3. 在容器内验证

命令执行后，你的终端提示符会变为 /#，表示已进入容器内部。

查看宿主机容器:
```
# 在容器内部执行
docker ps
```
输出结果会列出你宿主机上所有正在运行的容器，包括你刚刚启动的这一个。这证明容器已成功连接到宿主机的 Docker 服务。
运行一个新容器:
```
# 在容器内部执行
docker run --rm hello-world
```
你会看到 hello-world 镜像被成功拉取并运行。此时，你在宿主机上执行 docker images，也能看到 hello-world 这个镜像，证明了缓存是共享的。

方法二：真正的 Docker-in-Docker (DinD) - 特定场景使用

⚠️ 安全警告 此方法必须开启 --privileged (特权)模式，这会打破容器的隔离性，给予容器访问宿主机内核的权限，存在严重的安全风险。请仅在完全信任镜像内容，并确实需要强隔离环境时使用。

✨ 原理

使用官方提供的 docker:dind 镜像，在容器内启动一个完整的、独立的 Docker 守护进程。

❌ 缺点

安全风险高：--privileged 模式是危险的。
性能开销大：双重 Docker Daemon 运行，消耗更多系统资源。
双重存储：内外镜像是隔离的，同一镜像需要下载两次，占用双倍磁盘空间。

🚀 操作步骤

1. 启动 DinD 守护进程容器

这个容器专门用来在后台运行独立的 Docker 服务。

docker run --privileged --name my-dind-daemon -d \
 -e DOCKER_TLS_CERTDIR=/certs \
 docker:24.0-dind

命令解析:

--privileged: (高危) 授予容器特权。
--name my-dind-daemon: 为该容器命名，方便后续连接。
-d: 后台运行。
docker:24.0-dind: 使用官方的 dind 专用镜像。

2. 启动客户端容器并连接到 DinD

现在启动另一个容器作为客户端，并将其网络连接到刚才的 dind 容器。

docker run -it --rm \
 --link my-dind-daemon:docker \
 docker:24.0 \
 sh

命令解析:

--link my-dind-daemon:docker: 核心命令。将 my-dind-daemon 容器连接到当前容器，并设置网络别名为 docker。这样，客户端内的 Docker CLI 就会自动找到名为 docker 的主机作为其守护进程。
docker:24.0: 使用普通的 docker 镜像作为客户端。

3. 在客户端容器内验证

进入客户端容器后，进行验证。

查看容器:
```
# 在客户端容器内执行
docker ps
```
输出结果应为空。因为它连接的是 my-dind-daemon 提供的全新、隔离的环境。
运行一个新容器:
```
# 在客户端容器内执行
docker run --rm hello-world
```
hello-world 镜像会被下载并运行。这个容器完全存在于 my-dind-daemon 的环境中，你的宿主机对此毫不知情。在宿主机上执行 docker ps 或 docker images 都看不到这个 hello-world。

使用已有容器创建镜像

docker commit container-name new-image-name

开启/重启ssh服务

service ssh start
service ssh restart

docker 文件传输

宿主机到容器

# docker cp 宿主机文件/路径 容器名：容器内路径
docker cp /home/Download/index.html wordpress-lee:/var/www/html

容器到宿主机

# docker cp 容器名：文件/路径 宿主机路径 
docker cp wordpress-lee:/root/example.sh /root

修改服务器配置允许通过此服务器进行ssh转发

进入配置文件，不要cd..然后在vim，直接vim …

vim /etc/ssh/sshd_config

配置文件内容

修改其中的：

重启ssh服务

 service ssh restart

docker容器添加对外映射端口

参考：
https://www.cnblogs.com/zhumengke/articles/13525837.html

最简单省事方法：将现有的容器打包成镜像，然后在使用新的镜像运行容器时重新指定要映射的端口

局域网访问Docker容器完整指南

这个问题非常常见，是团队协作或使用多台设备进行开发时必备的技能。

另一台局域网上的电脑（我们称之为"开发机"）要进入运行 Docker 的电脑（我们称之为"主机"）的容器，核心思想是通过网络暴露容器的服务或端口。容器本身是隔离的，你需要"开一个门"让局域网上的其他设备可以访问。

这里有几种主流的方法，从简单到复杂，适用于不同的开发场景。

准备工作：必须知道主机IP

首先，你需要在运行 Docker 的主机上获取其局域网 IP 地址。

在 Windows 上: 打开命令提示符（CMD）或 PowerShell，输入 ipconfig，查找 “IPv4 地址”。通常是 192.168.x.x 或 10.x.x.x 的形式。
在 macOS 或 Linux 上: 打开终端，输入 ifconfig 或 ip a，查找 inet 后面的地址。

下文中，我们假设主机的 IP 地址是 192.168.1.100。请在你的实际操作中替换成你自己的主机 IP。

方法一：端口映射 (Port Mapping) - 最常用

这是最直接、最常见的方法，适用于访问容器内运行的 Web 应用、API 服务、数据库等。

原理： 将主机的一个端口映射到容器内的一个端口。这样，访问主机的这个端口就等于访问了容器内的对应端口。

操作步骤：

启动容器时添加 -p 参数： 在主机上，当你使用 docker run 启动容器时，必须使用 -p 或 --publish 参数来暴露端口。

格式为：-p <主机端口>:<容器端口>

关键点： 为了让局域网上的其他电脑能访问，主机端口部分必须绑定到 0.0.0.0，或者干脆省略 IP 地址（默认就是 0.0.0.0）。
- 示例1：运行一个 Nginx Web 服务器
```
# 将主机的 8080 端口映射到容器的 80 端口
# 这样局域网内的任何机器都可以通过主机的 8080 端口访问
docker run -d --name my-web -p 8080:80 nginx
```
- 示例2：运行一个 Python Flask 应用 假设你的 Flask 应用在容器的 5000 端口运行。
```
# 将主机的 5000 端口映射到容器的 5000 端口
docker run -d --name my-app -p 5000:5000 your-python-app-image
```
在开发机上访问： 现在，在局域网的另一台开发机上，打开浏览器或使用工具（如 cURL, Postman）访问 http://<主机IP>:<主机端口>。
- 对于上面的 Nginx 示例，访问地址是：http://192.168.1.100:8080
- 对于 Flask 应用示例，访问地址是：http://192.168.1.100:5000

如果容器已经启动了怎么办？ 你不能动态地给一个正在运行的容器添加端口映射。你需要停止并删除旧的容器，然后使用新的 -p 参数重新启动它。

docker stop <容器名或ID>
docker rm <容器名或ID>
# 然后使用上面的 docker run -p ... 命令重新创建

方法二：通过 SSH 进入容器 - 获取完整的 Shell 环境

如果你需要在容器内部执行命令、调试脚本，就像登录一台远程服务器一样，那么在容器里运行一个 SSH 服务是最佳选择。

原理： 在你的 Docker 镜像中安装并运行一个 SSH 服务器，然后像方法一那样，将容器的 SSH 端口（默认为 22）映射到主机的一个端口。

操作步骤：

准备一个带 SSH 服务的 Dockerfile： 你不能直接在官方的基础镜像（如 ubuntu）里直接用 SSH，需要先安装。

下面是一个基于 Ubuntu 的 Dockerfile 示例：

# 使用一个基础镜像
FROM ubuntu:20.04

# 安装 SSH 服务端和一些常用工具
RUN apt-get update && apt-get install -y openssh-server sudo vim curl \
 && rm -rf /var/lib/apt/lists/*

# 创建一个用于 SSH 登录的用户，并设置密码
# 注意：在生产环境中，不要用硬编码的密码！
RUN useradd -m -s /bin/bash developer && echo "developer:yourpassword" | chpasswd && adduser developer sudo

# 允许 root 登录（仅用于开发，不推荐在生产中使用）
RUN sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config

# 创建 SSH 服务运行所需的目录
RUN mkdir /var/run/sshd

# 暴露容器的 22 端口
EXPOSE 22

# 容器启动时运行 SSH 服务
CMD ["/usr/sbin/sshd", "-D"]

构建并运行镜像：
- 在主机上，将上述 Dockerfile 保存，然后在该目录下执行构建命令：
```
docker build -t my-ssh-container .
```
- 运行容器，并将主机的 2222 端口映射到容器的 22 端口（使用 2222 是为了避免与主机本身的 SSH 服务冲突）：
```
docker run -d --name dev-env -p 2222:22 my-ssh-container
```
在开发机上通过 SSH 连接： 在你的开发机上，打开终端，使用 ssh 命令连接。
```
# 使用你创建的 developer 用户登录
ssh developer@192.168.1.100 -p 2222
```
然后输入你设置的密码 (yourpassword)，就可以进入容器的命令行界面了。

方法三：使用 VS Code Remote Development - 最现代化的开发体验

这是目前最受推崇的开发方式，它结合了本地 IDE 的流畅体验和容器化环境的隔离与一致性。

原理： 你在本地的 VS Code 上编写代码，但所有的文件操作、终端命令、调试器都运行在远程主机上的容器内部。VS Code 会在容器里安装一个轻量的服务来实现这种无缝连接。

操作步骤：

在主机上：暴露 Docker Daemon 这是最关键的一步。你需要让 Docker 守护进程监听一个 TCP 端口，以便远程的 VS Code 可以连接。
- 对于 Docker Desktop (Windows/macOS): 进入 Settings -> General，勾选 “Expose daemon on tcp://localhost:2375 without TLS”。
- 对于 Linux: 编辑 Docker 的配置文件 /etc/docker/daemon.json (如果不存在则创建)，添加以下内容：
```
{
 "hosts": ["tcp://0.0.0.0:2375", "unix:///var/run/docker.sock"]
}
```
  然后重启 Docker 服务：
```
sudo systemctl restart docker
```
安全警告： 将 Docker Daemon 暴露在网络上存在安全风险，请确保你的局域网是受信任的，并且主机防火墙已正确配置。

在主机上：确保你的开发容器正在运行。

# 只需要一个普通的开发容器即可，无需特殊配置
docker run -d --name my-project-container -it your-dev-image bash

-it 和 bash 让容器保持运行状态。

在开发机上：配置 VS Code
- 安装 VS Code。
- 在 VS Code 的扩展市场中，搜索并安装 Remote Development 扩展包（由 Microsoft 发布）。
- 打开 VS Code 的设置 (Settings JSON)，添加以下配置，告诉它 Docker 主机在哪里：
```
{
 "docker.host": "tcp://192.168.1.100:2375"
}
```
- 重启 VS Code。
在开发机上：连接到容器
- 点击 VS Code 左下角的绿色 >< 图标，或者按 F1 输入 Remote-Containers: Attach to Running Container...。
- VS Code 会列出主机 192.168.1.100 上所有正在运行的容器。
- 选择你的目标容器（例如 my-project-container）。
- VS Code 会自动在容器内安装所需的服务，并重新加载窗口。完成后，你的 VS Code 就已经"进入"了容器。你可以直接打开容器内的文件夹、使用 VS Code 的集成终端（这个终端就是容器的 shell）、安装语言扩展、进行调试等，一切都像在本地一样。

总结与选择

方法	适用场景	优点	缺点
端口映射	访问 Web 服务、API、数据库等需要端口的应用。	简单、直接、最常用。	只能访问暴露的服务，无法直接操作容器内部文件系统或执行任意命令。
SSH 进入容器	需要完整的命令行权限，进行系统管理、脚本调试。	功能强大，像操作一台真实的 Linux 服务器。	配置相对复杂，需要在镜像中预置 SSH 服务和用户。
VS Code Remote	现代化的编码、调试、测试一体化开发。	体验最佳，无缝集成，兼具本地 IDE 的流畅和容器环境的隔离。	需要配置 Docker Daemon，有一定安全风险，依赖 VS Code。

强烈建议：

对于查看和测试 Web 应用，使用方法一。
对于需要深入容器内部进行复杂操作的场景，使用方法二。
对于日常编码和开发，强烈推荐学习并使用方法三，这是目前最先进、最高效的流程。

最后，请务必检查主机的防火墙，确保你映射的端口（如 8080, 2222, 2375）是开放的，允许来自局域网的访问。

docker设置可用CPU核心数量

参考：
https://www.cnblogs.com/sparkdev/p/8052522.html

容器端口转发问题排查和解决方案

在容器中进行端口转发并遇到无法访问的问题，可能涉及多个原因。以下是详细的分析和可能的原因，以及解决方法：

1. 容器端口转发的工作原理

Docker 的端口转发通过 -p 或 -P 参数实现：

-p <主机端口>:<容器端口>：显式地将主机的某个端口映射到容器的某个端口。例如，-p 5980:5980 会将主机的 5980 端口映射到容器的 5980 端口。
-P（大写）：自动将容器 Dockerfile 中通过 EXPOSE 指令暴露的端口随机映射到主机的高位端口（通常是 32768 以上的端口）。

当你使用 -P 参数时，Docker 会自动分配一个主机端口，而不是直接使用容器内的端口（比如 5980）。因此，访问 http://localhost:5980 可能失败，因为主机的 5980 端口并未映射到容器的 5980 端口。

检查方法：运行以下命令查看端口映射：

docker ps

或

docker port <容器名称或ID>

输出会显示类似 0.0.0.0:49153->5980/tcp 的信息，表示容器内的 5980 端口被映射到主机的 49153 端口。你需要访问 http://localhost:49153 而不是 http://localhost:5980。

解决方法：如果你希望明确映射到主机的 5980 端口，创建容器时使用：

docker run -p 5980:5980 <镜像名称>

这样容器内的 5980 端口会直接映射到主机的 5980 端口。

2. SSL 配置导致的问题

你提到后端服务启用了 SSL（HTTPS）。这意味着服务可能在容器内监听的是 HTTPS 协议（https://），而不是 HTTP 协议（http://）。如果你尝试访问 http://localhost:5980，可能会因为协议不匹配而失败。

可能原因：

服务在容器内运行在 HTTPS 模式（默认 443 端口或你配置的 5980 端口），但你尝试用 HTTP 访问。
SSL 证书配置错误，导致服务无法正常响应。

检查方法：

确认服务是否使用 HTTPS：
- 检查你的后端服务配置文件（例如 Spring Boot 的 application.properties 或 Node.js 的 HTTPS 配置），确认监听的协议和端口。
- 如果服务监听的是 HTTPS，访问时需要使用 https://localhost:5980 而不是 http://localhost:5980。
检查容器内的服务是否正常运行：
```
docker exec -it <容器名称或ID> bash
```
进入容器后，运行 netstat -tuln 或 ss -tuln 检查 5980 端口是否在监听。如果没有，说明服务未正确启动。
检查 SSL 证书：
- 确保 SSL 证书和密钥文件已正确挂载到容器中（通过 -v 挂载卷或 Dockerfile 复制）。
- 确保证书有效（未过期，主机名匹配等）。

解决方法：

如果服务使用 HTTPS，访问时使用 https://localhost:5980。
如果证书有问题，尝试临时禁用 SSL（用于测试），或确保证书正确配置。
如果你希望继续使用 HTTP，检查服务是否支持 HTTP 模式（例如，修改配置文件将服务切换到 HTTP）。

3. 主机与容器的网络问题

Docker 容器默认运行在桥接网络（bridge network）中，主机和容器之间的网络通信需要正确配置。

可能原因：

防火墙或安全组阻止了主机的 5980 端口（或随机映射的端口）。
容器网络模式配置错误（例如使用了 host 网络模式但未正确配置）。
服务绑定了错误的网络接口（例如只绑定了 127.0.0.1，而不是 0.0.0.0）。

检查方法：

确认服务监听的 IP 地址：
- 进入容器，运行 netstat -tuln 检查服务是否绑定到 0.0.0.0:5980（接受所有接口的连接）或 127.0.0.1:5980（仅接受本地连接）。
- 如果绑定到 127.0.0.1，容器外部无法访问。
检查主机防火墙：
- 在 Linux 上运行 iptables -L 或 ufw status 检查是否阻止了 5980 端口。
- 在 Windows/Mac 上，检查系统防火墙设置。
检查 Docker 网络模式：
- 如果你使用了 --network host，容器直接使用主机的网络，端口映射（-p 或 -P）无效，服务端口需要与主机一致。
- 如果使用默认桥接网络，确保端口映射正确。

解决方法：

确保服务监听 0.0.0.0 而不是 127.0.0.1。在后端服务配置中修改监听地址（例如 Spring Boot 的 server.address=0.0.0.0）。
开放主机防火墙的相应端口：
```
sudo ufw allow 5980
```
如果不需要桥接网络，可以尝试使用 --network host 运行容器：
```
docker run --network host <镜像名称>
```
但注意这会绕过 Docker 的端口映射机制，容器直接使用主机端口。

4. 本机运行 vs. 容器运行的差异

你提到在本机运行代码可以访问，但在容器中无法访问。以下是可能的原因：

环境差异：
- 本机运行时，服务可能默认监听 HTTP 或绑定到 127.0.0.1，而容器中可能配置不同。
- 容器中的环境变量、配置文件或依赖可能与本机不一致。
端口冲突：
- 如果主机上已有其他服务占用了 5980 端口，Docker 端口映射可能失败。
证书路径问题：
- 容器内的 SSL 证书路径可能与本机不同，导致服务启动失败或无法响应 HTTPS 请求。

检查方法：

比较本机和容器的服务配置：
- 检查本机和容器中的配置文件（例如 application.properties 或 config.json）。
- 确保环境变量（通过 docker run -e 设置）一致。
检查主机端口占用：
```
netstat -tuln | grep 5980
```
如果 5980 端口已被占用，尝试使用其他端口映射（例如 -p 5981:5980）。
检查容器日志：
```
docker logs <容器名称或ID>
```
查看服务是否启动成功，是否有 SSL 或端口相关的错误。

解决方法：

确保容器内的配置文件与本机一致。
如果端口冲突，释放主机上的 5980 端口或使用其他端口映射。
检查日志并修复启动错误（例如缺少依赖、证书路径错误等）。

5. 如何调试和解决

按照以下步骤逐步排查：

确认端口映射：
- 使用 docker port <容器名称或ID> 查看实际映射的端口。
- 尝试访问正确的映射端口（例如 http://localhost:<映射端口> 或 https://localhost:<映射端口>）。
检查服务状态：
- 进入容器，确认服务是否在 5980 端口监听，并检查绑定地址（0.0.0.0 或 127.0.0.1）。
- 检查日志是否有错误。
测试 HTTPS：
- 使用 curl -k https://localhost:5980（-k 忽略证书验证）测试是否能连接。
- 如果失败，检查 SSL 配置或尝试 HTTP。

尝试显式端口映射：

停止并删除当前容器，重新运行：

docker stop <容器名称或ID>
docker rm <容器名称或ID>
docker run -p 5980:5980 <镜像名称>

检查网络和防火墙：
- 确保主机防火墙允许 5980 端口。
- 如果在云服务器上运行，检查安全组规则是否开放 5980 端口。

6. 总结

你无法访问 http://localhost:5980 的主要原因可能是：

使用 -P 参数导致主机端口不是 5980（而是随机端口）。
服务使用 HTTPS，但你尝试用 HTTP 访问。
服务绑定了 127.0.0.1 而不是 0.0.0.0，或存在端口冲突。
SSL 证书配置错误或容器环境与本机不一致。

推荐步骤：

使用 docker port 检查实际映射端口，尝试访问正确的端口。
确保访问协议正确（HTTP 或 HTTPS）。
使用显式端口映射 -p 5980:5980 重启容器。
检查容器日志和服务配置，确保与本机运行一致。
如果问题仍未解决，提供以下信息以便进一步分析：
- 你的 docker run 完整命令。
- 容器日志（docker logs <容器ID>）。
- 服务配置文件或代码片段（涉及端口和 SSL 配置的部分）。

如果需要更具体的帮助，请提供上述信息，我可以进一步协助你！

docker实战

Docker使用实战-容器保存和迁移

在 Docker 中，如果你想保存一个容器，可以将其保存为镜像（image），然后在需要时基于这个镜像重新创建容器。以下是具体步骤：

方法一：将容器保存为镜像

查看正在运行的容器 使用以下命令列出当前运行的容器，找到你要保存的容器 ID 或名称：
```
docker ps -a
```
提交容器为镜像 使用 docker commit 命令将容器保存为一个新的镜像。假设你的容器 ID 是 abc123，你想保存为镜像名称 myimage:latest：
```
docker commit abc123 myimage:latest
```
- abc123 是容器 ID 或容器名称。
- myimage:latest 是你想保存的新镜像名称和标签。
验证镜像 保存后，可以用以下命令查看新创建的镜像：
```
docker images
```

（可选）保存镜像到文件 如果你想将镜像导出为一个 .tar 文件以便备份或转移到其他机器：

docker save -o myimage.tar myimage:latest

 # 或者
# 将镜像传递到远程服务器 将 your-user@your-server 替换为你的 SSH 登录信息
docker save my-x86-app:1.0 | ssh your-user@your-server 'docker load'

这样会生成一个 myimage.tar 文件。

（可选）加载镜像 在其他地方使用时，可以通过以下命令加载 .tar 文件：
```
docker load -i myimage.tar
```

方法二：直接导出容器

如果你不需要将其转化为镜像，而是想直接保存容器的完整状态（包括文件系统和配置），可以用 docker export：

docker export abc123 > container.tar

这会将容器导出为一个 .tar 文件。
之后可以用 docker import 导入这个文件为镜像：
```
docker import container.tar myimage:latest
```

注意事项

docker commit vs docker export：
- docker commit 保存的是容器的运行时状态为一个新镜像，适合需要保留容器修改的情况。
- docker export 导出的只是文件系统快照，不包括容器的元数据（如 CMD、ENTRYPOINT 等）。
推荐方式：通常建议使用 docker commit 并结合 Dockerfile 来管理镜像，这样更符合 Docker 的最佳实践。

使用保存的镜像

保存为镜像后，随时可以用以下命令基于镜像启动新容器：

docker run -d myimage:latest

如果你有其他具体需求（比如保存到某个地方或自动化脚本），可以告诉我，我再帮你调整方案！

Docker 服务部署教程

在开始之前，我们先快速理解三个最重要的概念：

Docker：一个开源平台，用于开发、发布和运行应用程序。它允许你将应用程序及其所有依赖（库、环境变量、配置文件等）打包到一个标准化的单元中，这个单元被称为“容器”。
镜像 (Image)：一个只读的模板，包含了运行应用程序所需的所有内容——代码、运行时、库、环境变量和配置文件。你可以把镜像理解为安装程序或一个“蓝图”。
容器 (Container)：镜像的运行实例。当你运行一个镜像，你就启动了一个容器。容器是独立的、轻量级的，并且在你的主机操作系统上运行，但与主机和其他容器隔离。你可以同时运行同一个镜像的多个容器。

简单比喻：

Dockerfile 是菜谱。
镜像 (Image) 是做好的、打包在盒子里的预制菜。
容器 (Container) 是你把预制菜放进微波炉加热后，正在运行、可以享用的那份饭菜。

环境准备

在开始之前，你需要在你的机器上安装 Docker。

Windows / macOS: 下载并安装 Docker Desktop。它提供了一个图形化界面和命令行工具。
- 官方下载地址: https://www.docker.com/products/docker-desktop/
Linux: 根据你的发行版（如 Ubuntu, CentOS）按照官方文档进行安装。
- 官方安装指南: https://docs.docker.com/engine/install/

安装完成后，打开你的终端（在 Windows 上是 PowerShell 或 WSL2，macOS 上是 Terminal），运行以下命令来验证 Docker 是否安装成功：

docker --version
docker ps

如果命令能够成功执行并显示版本信息和一个空的容器列表，说明 Docker 已经准备就绪。

实战演练：部署一个 Python Web 应用

我们将部署一个简单的 Python Flask Web 应用，它会在访问时返回 “Hello, Docker!"。

步骤一：准备应用程序

首先，在你喜欢的位置创建一个新的项目文件夹，例如 my-docker-app。

mkdir my-docker-app
cd my-docker-app

在该文件夹中，创建以下两个文件：

app.py (我们的 Web 应用程序代码)

from flask import Flask

# 创建 Flask 应用实例
app = Flask(__name__)

# 定义根路由
@app.route('/')
def hello():
 return "Hello, Docker! This is a simple web service."

# 启动服务
# host='0.0.0.0' 让容器外部可以访问
# port=5000 是应用监听的端口
if __name__ == '__main__':
 app.run(host='0.0.0.0', port=5000)

requirements.txt (列出 Python 依赖)
```
Flask==2.2.2
```

现在你的文件夹结构应该是：

my-docker-app/
├── app.py
└── requirements.txt

步骤二：编写 Dockerfile

Dockerfile 是一个文本文件，它包含了构建 Docker 镜像所需的所有指令。在 my-docker-app 文件夹中创建名为 Dockerfile (没有文件扩展名) 的文件。

# 步骤 1: 选择一个基础镜像
# 我们选择一个官方的、轻量级的 Python 3.9 镜像
FROM python:3.9-slim

# 步骤 2: 在镜像中设置工作目录
# 之后的所有命令都会在这个目录下执行
WORKDIR /app

# 步骤 3: 复制依赖文件到工作目录
# 将 requirements.txt 复制到镜像的 /app 目录中
COPY requirements.txt .

# 步骤 4: 安装应用程序的依赖
# 在镜像中运行 pip 命令来安装 Flask
RUN pip install --no-cache-dir -r requirements.txt

# 步骤 5: 复制应用程序代码到工作目录
# 将当前目录下的所有文件 (app.py) 复制到镜像的 /app 目录
COPY . .

# 步骤 6: 声明容器将监听的端口
# 这只是一个元数据声明，告诉用户这个容器内部的应用会使用 5000 端口
EXPOSE 5000

# 步骤 7: 定义启动容器时要执行的命令
# 运行我们的 Python 应用
CMD ["python", "app.py"]

步骤三：构建 Docker 镜像

现在我们有了应用程序和 Dockerfile，可以构建我们的镜像了。确保你的终端当前路径在 my-docker-app 文件夹下。

运行 docker build 命令：

# -t my-web-app:v1 给镜像起一个名字 (tag)，格式是 <name>:<version>
# . 表示使用当前目录下的 Dockerfile
docker build -t my-web-app:v1 .

你会看到 Docker 按照 Dockerfile 中的步骤逐一执行。构建成功后，你可以用以下命令查看你刚刚创建的镜像：

docker images

你应该能在列表中看到 my-web-app 这个镜像。

步骤四：运行 Docker 容器

镜像已经构建好了，现在让我们用它来启动一个容器。

运行 docker run 命令：

docker run -d -p 8888:5000 --name my-first-container my-web-app:v1

让我们分解一下这个命令：

docker run: 运行一个容器的命令。
-d (detached): 后台运行模式。容器将在后台启动并持续运行。
-p 8888:5000 (port mapping): 端口映射。这是非常重要的一步。
- 它将宿主机 (你的电脑) 的 8888 端口映射到容器的 5000 端口。
- 5000 是我们在 app.py 和 Dockerfile 中指定的应用端口。
- 8888 是我们希望通过外部访问的端口。你可以换成其他未被占用的端口，如 80。
--name my-first-container: 给这个正在运行的容器起一个友好的名字，方便管理。
my-web-app:v1: 指定要运行的镜像。

步骤五：验证和管理

验证服务 打开你的浏览器，访问 http://localhost:8888。你应该能看到页面上显示 “Hello, Docker! This is a simple web service."。

你也可以使用 curl 命令在终端验证：
```
curl http://localhost:8888
```
管理容器 以下是一些常用的容器管理命令：
- 查看正在运行的容器
```
docker ps
```
- 查看容器日志 (非常适合排查问题)
```
docker logs my-first-container
```
- 停止容器
```
docker stop my-first-container
```
- 重新启动已停止的容器
```
docker start my-first-container
```
- 删除容器 (必须先停止容器才能删除)
```
docker rm my-first-container
```
- 删除镜像 (必须先删除所有使用该镜像的容器才能删除)
```
docker rmi my-web-app:v1
```

进阶：使用 Docker Compose 编排服务

当你的应用变得复杂，比如需要一个 Web 服务和一个数据库服务时，手动管理多个容器会很麻烦。Docker Compose 就是解决这个问题的工具。它允许你使用一个 YAML 文件来定义和运行多容器的 Docker 应用程序。

步骤一：安装 Docker Compose

如果你安装的是 Docker Desktop (Windows/macOS)，那么 Docker Compose 已经包含在内了。你可以通过 docker-compose --version 或 docker compose version 来验证。

步骤二：创建 `docker-compose.yml` 文件

在你的 my-docker-app 文件夹中，创建一个名为 docker-compose.yml 的文件。

# docker-compose.yml

# 定义 Compose 文件的版本
version: '3.8'

# 定义服务
services:
 # 我们的 Web 应用服务
 web:
 # 构建指令
 build:
 # 使用当前目录下的 Dockerfile
 context: .
 # 镜像名称
 image: my-web-app-compose:latest
 # 容器名称
 container_name: my-web-app-container
 # 端口映射
 ports:
 - "8888:5000"
 # 卷挂载 (可选，用于代码热更新)
 # 将本地代码目录挂载到容器的 /app 目录
 # 这样修改本地代码后，服务会自动重启（需要 Flask 开启 debug 模式）
 volumes:
 - .:/app
 # 环境变量
 environment:
 - FLASK_ENV=development # 开启 Flask 调试模式

 # 假设我们还需要一个 Redis 服务
 redis:
 # 直接使用官方 Redis 镜像
 image: "redis:alpine"
 container_name: my-redis-cache

步骤三：使用 Docker Compose 启动服务

在 my-docker-app 目录下，运行以下命令：

# 启动所有服务 (-d 表示后台运行)
docker-compose up -d
# 或者新版本命令
# docker compose up -d

Compose 会自动帮你：

构建 web 服务的镜像（如果尚未构建）。
拉取 redis 镜像。
创建并启动 web 和 redis 两个容器，并根据配置建立网络连接。

步骤四：管理 Compose 服务

查看服务状态
```
docker-compose ps
```

查看日志

docker-compose logs -f web # 查看 web 服务的日志

停止并删除所有服务
```
docker-compose down
```

总结

恭喜你！你已经学会了如何使用 Docker 部署一个单服务的 Web 应用，并了解了如何使用 Docker Compose 管理更复杂的应用场景。

核心流程回顾：

写代码 (app.py, requirements.txt)
写配置 (Dockerfile)
构建镜像 (docker build)
运行容器 (docker run 或 docker-compose up)

Docker 的世界非常广阔，接下来你可以继续探索数据持久化（Volumes）、网络（Networking）、以及如何将你的镜像推送到 Docker Hub 与他人共享。

Docker服务部署教程2-使用uv替代pip

好的，当然可以。使用 uv 来替代 pip 进行包管理是一个非常棒的选择，尤其是在 Docker 构建环境中，因为 uv 的速度极快，可以显著缩短镜像构建的时间。

改动主要集中在 Dockerfile 文件中。你需要添加安装 uv 的步骤，并用 uv pip install 替换 pip install。你的应用程序代码 (app.py) 和依赖列表 (requirements.txt) 完全不需要改变。

下面是详细的说明和更新后的代码。

使用 UV 的核心改动

uv 是一个独立的二进制文件，我们需要在 Docker 镜像中先安装它。最直接的方法是使用官方提供的安装脚本。

更新后的 Dockerfile 会包含以下几个新步骤：

安装 curl 工具，以便下载 uv 安装脚本。
运行 uv 的安装脚本。
将 uv 的路径添加到环境变量 PATH 中，以便后续命令可以找到它。
使用 uv 来安装依赖。

更新后的 `Dockerfile` (使用 uv)

这是修改后的 Dockerfile。你可以直接用它替换掉原来项目中的 Dockerfile。

# Use a Python image with uv pre-installed
FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim

# Set working directory
WORKDIR /app

# Enable bytecode compilation
ENV UV_COMPILE_BYTECODE=1

# Copy from the cache instead of linking since it's a mounted volume
ENV UV_LINK_MODE=copy

# Copy requirements file first for better layer caching
COPY requirements.txt .

# Install dependencies using uv with requirements.txt
RUN --mount=type=cache,target=/root/.cache/uv \
 uv pip install --system -r requirements.txt

# Copy application code
COPY . .

# Expose port 5000 (Flask default)
EXPOSE 5000

# Reset the entrypoint, don't invoke `uv`
ENTRYPOINT []

# Run the Flask application
CMD ["python", "app.py"]

你的整体工作流程几乎不变，只是替换了 Dockerfile 的内容。之前使用gemini的教程但是报错了所以最好使用uv官方提供的镜像，具体使用教程可见

在 Docker 中使用 uv

使用 UV 的完整流程

```bash
docker build -t my-web-app:uv-latest .
```
（我们用了 `uv-latest` 这个新标签来区分版本）
在这一步，你会注意到 `RUN uv pip install` 这一层会比之前使用 `pip` 快非常多，尤其是在依赖项很多的情况下。

运行容器（命令不变） 使用新的镜像标签来运行容器：

docker run -d -p 8888:5000 --name my-uv-container my-web-app:uv-latest

验证（方式不变） 访问 http://localhost:8888，一切应该和之前一样正常工作。

对于 Docker Compose 呢？

你的 docker-compose.yml 文件完全不需要任何改动。

# docker-compose.yml (无需改动)
version: '3.8'
services:
 web:
 build:
 context: .
 ports:
 - "8888:5000"
 # ... 其他配置

这就是 Docker 的强大之处。docker-compose.yml 只关心“做什么”（比如，从当前目录 . 构建一个镜像），而不关心“怎么做”（具体是使用 pip 还是 uv 来安装依赖）。所有的实现细节都被封装在 Dockerfile 里了。当你运行 docker-compose up 时，Compose 会自动使用你更新后的 Dockerfile 来构建镜像。

总结

将包管理器从 pip 切换到 uv，你只需要：

更新 Dockerfile 以包含安装和使用 uv 的指令。
重新 build 你的镜像。

其他所有代码、文件和部署命令都保持原样，流程无缝衔接，同时还能享受到 uv 带来的极致构建速度。

docker容器的部署教程3-将容器部署到服务器上

当你创建完 Dockerfile 之后，部署一个应用通常遵循一个标准化的流程：构建镜像 -> 推送镜像 -> 在目标环境运行容器。

下面我将为你分解这个过程，并介绍从简单到复杂的不同部署方案。

核心流程

第一步：构建 Docker 镜像 (Build)

这是将你的 Dockerfile 和应用程序代码打包成一个标准化的、不可变的“Docker 镜像”的过程。

在你的 Dockerfile 所在的目录下，打开终端并运行以下命令：

# docker build -t <你的镜像名称>:<标签> .
# 示例:
docker build -t my-awesome-app:v1.0 .

docker build: 构建命令。
-t my-awesome-app:v1.0: -t 参数用来给镜像打上“标签”（tag），格式通常是 image_name:version。这非常重要，便于版本管理。
.: 这个点表示 Dockerfile 的上下文路径（Context Path）是当前目录。Docker 会把这个目录下的所有文件发送给 Docker 守护进程来帮助构建。

构建成功后，你可以通过 docker images 命令查看你本地的所有镜像。

第二步：在本地运行和测试 (Run Locally)

在推送到服务器之前，首先在本地运行容器以确保它能正常工作。

# docker run --rm -p <本地端口>:<容器端口> <你的镜像名称>:<标签>
# 示例: 假设你的应用在容器内监听 8080 端口
docker run --rm -p 3000:8080 my-awesome-app:v1.0

docker run: 运行命令。
--rm: 容器停止后自动删除，适合测试。
-p 3000:8080: -p 参数用来做端口映射（Port Mapping），将你本机的 3000 端口映射到容器的 8080 端口。这样你就可以通过访问 http://localhost:3000 来访问你的应用了。
my-awesome-app:v1.0: 指定要运行的镜像。

第三步：推送镜像到镜像仓库 (Push to Registry)

为了在其他机器（例如你的云服务器）上使用这个镜像，你需要将它推送到一个中央存储库，这被称为“镜像仓库”（Image Registry）。

最常用的公共仓库是 Docker Hub。各大云服务商也提供私有仓库，如 Google Artifact Registry (GCR), Amazon Elastic Container Registry (ECR), Azure Container Registry (ACR) 等。

为镜像打上符合仓库要求的标签：推送前，你需要将镜像重命名为 <你的仓库用户名>/<镜像名称>:<标签> 的格式。

# 格式: docker tag <本地镜像> <仓库用户名>/<新镜像名>:<标签>
# 示例 (以 Docker Hub 为例):
docker tag my-awesome-app:v1.0 your-dockerhub-username/my-awesome-app:v1.0

登录你的镜像仓库：

# 登录 Docker Hub
docker login
# 按照提示输入你的 Docker Hub 用户名和密码
# 然后这个页面不要关，下面推送的时候打开一个新的终端

推送镜像：


# 格式: docker push <仓库用户名>/<镜像名>:<标签>
# 示例:
docker push your-dockerhub-username/my-awesome-app:v1.0

第四步：选择部署方案 (Deploy)

现在你的镜像已经准备就绪，可以部署了。以下是几种常见的部署方案，从易到难：

方案一：在单台云服务器上手动部署 (最简单)

这种方式适合个人项目、测试环境或小型应用。

准备服务器：购买一台云服务器（如 GCP, AWS, Azure, 阿里云等），并确保已安装 Docker。
SSH 登录服务器：通过 SSH 客户端连接到你的服务器。
拉取镜像：在服务器上，从你之前推送的仓库中拉取镜像。
```
docker pull your-dockerhub-username/my-awesome-app:v1.0
```
运行容器：与在本地运行类似，但在服务器上通常使用 -d 参数让容器在后台运行。
```
# -d (detached mode) 表示在后台运行容器
docker run -d -p 80:8080 --name my-running-app your-dockerhub-username/my-awesome-app:v1.0
```
这里我们将服务器的 80 端口（HTTP 默认端口）映射到容器的 8080 端口。现在，你可以通过服务器的 IP 地址直接访问你的应用。

方案二：使用 Docker Compose 部署 (推荐用于多容器应用)

如果你的应用包含多个服务（例如一个 Web 应用 +一个数据库），使用 Docker Compose 会让管理变得非常简单。

创建 docker-compose.yml 文件：在你的项目中创建一个 docker-compose.yml 文件。

version: '3.8'

services:
 app:
 image: your-dockerhub-username/my-awesome-app:v1.0
 ports:
 - "80:8080"
 restart: always # 容器挂掉后自动重启

 # 如果有数据库，可以这样添加
 # db:
 # image: postgres:13
 # environment:
 # - POSTGRES_PASSWORD=mysecretpassword

部署：将 docker-compose.yml 文件上传到你的服务器，然后在该文件所在的目录运行：

# 以后台模式启动所有服务
docker-compose up -d

# 如果需要更新镜像并重新部署
docker-compose pull # 拉取 yml 文件中定义的所有镜像的最新版
docker-compose up -d --force-recreate # 强制重新创建容器

方案三：部署到云平台的容器服务 (PaaS/Serverless)

这种方式可以让你不用管理底层服务器，只需提供容器镜像，平台会自动为你扩缩容和管理。

Google Cloud Run：非常简单的无服务器平台。你只需将镜像推送到 Google Artifact Registry，然后在 Cloud Run 上创建一个服务，指向这个镜像即可。平台按需计费，没有请求时不收费。
AWS App Runner / Azure Container Apps：与 Google Cloud Run 类似的服务。
Heroku：传统的 PaaS 平台，也支持通过 Docker 部署。

优点：免运维、自动扩缩容、按需付费。缺点：平台锁定性较强，自定义程度较低。

方案四：使用容器编排工具 (Kubernetes)

对于大型、复杂、高可用的生产系统，Kubernetes (K8s) 是事实上的标准。

它是什么：一个强大的系统，用于自动化部署、扩展和管理容器化应用程序。
何时使用：当你的应用需要高可用性、自动伸缩、滚动更新、服务发现和负载均衡等高级功能时。
如何使用：
1. 学习 Kubernetes 的基本概念（Pod, Deployment, Service 等）。
2. 编写 Kubernetes 的 YAML 配置文件来定义你的应用部署。
3. 使用云服务商提供的托管 Kubernetes 服务，如：
  - Google Kubernetes Engine (GKE)
  - Amazon Elastic Kubernetes Service (EKS)
  - Azure Kubernetes Service (AKS)

优点：极其强大和灵活，是微服务架构的最佳拍档。缺点：学习曲线非常陡峭，管理复杂。

如何选择？

方案	适用场景	优点	缺点
手动部署	个人项目、学习、快速原型	简单直接，易于理解	手动操作多，不易扩展和管理
Docker Compose	多容器的单机应用、开发和测试环境	大大简化多容器管理	主要面向单机，集群能力弱
云平台容器服务	中小型应用、无服务器爱好者	极简运维，自动扩缩容	平台锁定，不够灵活
Kubernetes	生产级、大型复杂系统、微服务架构	功能强大，高可用，可移植性好	学习曲线陡峭，非常复杂

对于初学者，我强烈建议你从 方案一 和 方案二 开始。 当你对容器化部署有了更深入的理解后，再根据项目需求去探索 方案三 和 方案四。

运行容器了但是并没有生效-通过查看日志解决问题

我运行容器了，但是访问localhost:8888并没有生效

好的，这是一个非常常见的问题，别担心，我们一步一步来排查。访问 localhost:8888 不生效通常有以下几个原因。

请打开你的终端，按顺序执行下面的命令来定位问题。

第一步：检查容器是否正在运行

首先，我们需要确认你的容器是否成功启动并且正在运行。

运行这个命令，它会列出所有正在运行的容器：

docker ps

你应该会看到类似这样的输出：

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
a1b2c3d4e5f6 my-web-app:v1 "python app.py" 2 minutes ago Up 2 minutes 0.0.0.0:8888->5000/tcp my-first-container

请检查几件事：

你的容器在列表里吗？
- 如果不在，说明容器启动失败或者已经退出了。请运行 docker ps -a (这会显示所有容器，包括已停止的)，找到你的容器 (my-first-container)，然后查看它的 STATUS。如果显示 Exited，请直接跳到下面的 第二步。
STATUS 是否是 Up？
- 如果状态是 Up，说明容器正在运行，这是个好消息。
PORTS 是否正确？
- 请仔细检查 PORTS 这一列。它必须显示 0.0.0.0:8888->5000/tcp 或类似的映射关系。这表示主机的 8888 端口已成功映射到容器的 5000 端口。如果这里是空的或者不正确，说明你运行 docker run 命令时 -p 参数可能有误。

第二步：查看容器日志

如果容器没有运行 (状态是 Exited)，或者虽然在运行但服务依然无法访问，那么最重要的一步就是查看日志。日志会告诉我们应用程序在容器内部发生了什么。

运行以下命令来获取容器的日志：

docker logs my-first-container

我这里看到这个错误，于是去from-werkzeugurls-import-url_quote-问题根源

分析日志输出：

情况A：看到错误信息 (Error)
- 如果你在日志中看到任何像 SyntaxError, ModuleNotFoundError, ImportError 或其他 Python 错误堆栈信息，说明是你的 app.py 代码有问题。请检查代码是否和教程中的完全一致。最常见的错误是 pip install 失败或者代码缩进错误。
情况B：看到 Flask 正常的启动信息
- 如果你看到类似下面的信息，说明 Flask 应用本身是正常启动的：
```
 * Serving Flask app 'app'
 * Running on http://0.0.0.0:5000
 * Press CTRL+C to quit
```
- 如果日志正常，但你依然无法访问，问题很可能出在 端口映射 或 网络/防火墙 上。

第三步：常见问题和解决方案汇总

根据以上检查，这里是问题排查的清单：

问题：容器启动后立即退出 (Exited)。
- 原因：应用代码有错误。
- 解决：运行 docker logs my-first-container 查看具体错误，修改 app.py 或 requirements.txt。修改后，你需要重新构建镜像并重新运行容器。
```
# 1. 停止并删除旧容器
docker rm my-first-container

# 2. 重新构建镜像
docker build -t my-web-app:v1 .

# 3. 重新运行容器
docker run -d -p 8888:5000 --name my-first-container my-web-app:v1
```
问题：容器在运行 (Up)，但 docker ps 的 PORTS 列是空的。
- 原因：运行容器时忘记了 -p 8888:5000 参数。
- 解决：停止并删除现有容器，然后使用正确的 docker run 命令重新运行。
```
docker stop my-first-container
docker rm my-first-container
docker run -d -p 8888:5000 --name my-first-container my-web-app:v1
```
问题：容器在运行，端口映射也正确，日志也正常，但就是无法访问。
- 原因1：你电脑的 8888 端口可能被其他程序占用了（比如另一个开发服务）。
- 解决1：尝试换一个主机端口，比如 8889。
```
docker stop my-first-container
docker rm my-first-container
docker run -d -p 8889:5000 --name my-first-container my-web-app:v1
```
  然后访问 http://localhost:8889。
- 原因2：防火墙或安全软件。公司电脑或一些安全软件可能会阻止端口访问。
- 解决2：暂时关闭防火墙或安全软件进行测试。
- 原因3 (特别是 Windows 用户)：如果你在使用一些旧版本的 Docker 或者网络配置特殊的虚拟机，localhost 可能无法直接映射。
- 解决3：尝试使用 127.0.0.1:8888 访问。如果还不行，可以找到 Docker 虚拟机的 IP 地址来访问。

请按照这个顺序排查，99% 的问题都能通过检查 容器状态 和 容器日志 来解决。如果你能把 docker ps 和 docker logs my-first-container 的输出结果贴出来，我可以给你更精确的诊断。

from werkzeug.urls import url_quote 问题根源

你遇到的错误是 ImportError: cannot import name 'url_quote' from 'werkzeug.urls'。

简单解释：你的应用程序（Flask）依赖于另一个名为 Werkzeug 的底层库。你安装的 Flask 版本 (2.2.2) 需要从 Werkzeug 库中导入一个叫做 url_quote 的函数。然而，pip 在安装依赖时，为你安装了一个非常新的 Werkzeug 版本（3.0 或更高版本），而在这个新版本中，url_quote 这个函数已经被移除了，从而导致了 ImportError（导入错误）。
为什么会发生？：在你的 requirements.txt 文件中，你只指定了 Flask==2.2.2。pip 在安装它时，会去自动安装 Flask 所需的依赖（比如 Werkzeug），并且通常会选择最新的可用版本。这就导致了 Flask (旧) 和 Werkzeug (新) 之间的不兼容。

解决方案

解决方法很简单：我们需要在 requirements.txt 中明确指定一个与 Flask==2.2.2 兼容的 Werkzeug 版本。Werkzeug 2.x 版本是兼容的。

请按照以下步骤操作：

第一步：修改 `requirements.txt`

打开你的项目文件夹中的 requirements.txt 文件，将其内容修改为：

Flask==2.2.2
Werkzeug==2.2.2

为什么要这样做？ 通过“锁定”或“固定”Werkzeug 的版本，我们确保了每次构建 Docker 镜像时，安装的都是经过测试、相互兼容的库版本组合。这正是 Docker 实现环境一致性和可复现性的核心思想之一。

第二步：停止并删除旧的容器

由于之前的容器是基于错误的镜像创建的，我们需要先清理它。

# 停止正在运行的容器（如果它还在尝试运行的话）
docker stop my-first-container

# 删除已停止的容器
docker rm my-first-container

如果命令提示 “No such container”，说明容器已经停止并被移除了，这没关系，直接进行下一步即可。

第三步：重新构建 Docker 镜像

由于我们修改了 requirements.txt，镜像的构建指令已经发生了变化，所以必须重新构建镜像。Docker 会很智能地利用缓存，只重新执行发生变化的步骤（即 RUN pip install 之后的步骤）。

在你的项目文件夹中，运行 build 命令：

docker build -t my-web-app:v1 .

![重构Docker镜像](images/index/index-14.png)

第四步：重新运行容器

现在，使用新构建的、包含了正确库版本的镜像来启动容器。

docker run -d -p 8888:5000 --name my-first-container my-web-app:v1

第五步：再次验证

等待几秒钟让容器启动，然后再次访问 http://localhost:8888。

这次，你应该就能成功看到 “Hello, Docker! This is a simple web service.” 的消息了。

这个错误完美地展示了为什么在 requirements.txt 中锁定依赖版本是如此重要，尤其是在使用 Docker 创建可复现、无意外的环境时。

wsl中镜像网络与docker网络冲突，使用netsh winsock reset修改网络设置之后，docker连不上 – 解决

报错信息

解决方法，将wsl setting的网络调到默认的nat模式，然后重置网络

然后就ok了

具有SSL证书的后端在docker环境中出现问题

首先，后端服务是放在dokcer容器中 0.0.0.0上的，然后看vscode的映射，最后记得改成https（第一次加载超级慢，而且可能连接失败）

如果使用http就无法访问

尽量还是不要在容器里面调试https吧

然后我试了127.0.0.1

2-github action 使用

Mon, 03 Mar 2025 00:00:00 +0800

参考：

常用知识

基础概念

Workflow（工作流）
工作流是一个自动化过程，定义在一或多个 YAML 文件中，存放在 .github/workflows 目录下。一个项目可以有多个工作流，他们顺序执行，你也可以在一个工作流里面引用执行另一个工作流
Event（事件）
触发工作流的事件，例如 push（推送代码）、pull_request（拉取请求）或定时触发。也可以手动执行，
Job（任务）
工作流中的一组步骤（Steps），运行在同一个虚拟机上。多个 Job 可以并行或按顺序执行。
Step（步骤）
Job 中的单个操作，例如运行命令或调用一个 Action。
Action（动作）
可重用的代码单元，通常由社区或官方提供，简化常见任务。
Runner（运行器）
执行工作流的服务器，GitHub 提供托管的 Runner，也支持自托管。
共享的action 很多操作在不同项目里面是类似的，完全可以共享。GitHub 注意到了这一点，想出了一个很妙的点子，允许开发者把每个操作写成独立的脚本文件，存放到代码仓库，使得其他开发者可以引用。

如果你需要某个 action，不必自己写复杂的脚本，直接引用他人写好的 action 即可，整个持续集成过程，就变成了一个 actions 的组合。这就是 GitHub Actions 最特别的地方。

GitHub 做了一个官方市场 https://github.com/marketplace?type=actions ，可以搜索到他人提交的 actions。另外，还有一个 awesome actions 的仓库 https://github.com/sdras/awesome-actions ，也可以找到不少 action。

每个 action 就是一个独立脚本，因此可以做成代码仓库，使用userName/repoName的语法引用 action。比如，actions/setup-node就表示github.com/actions/setup-node这个仓库，它代表一个 action，作用是安装 Node.js。事实上，GitHub 官方的 actions 都放在 github.com/actions 里面。既然 actions 是代码仓库，当然就有版本的概念，用户可以引用某个具体版本的 action。下面都是合法的 action 引用，用的就是 Git 的指针概念，详见官方文档。https://docs.github.com/en/actions/sharing-automations/creating-actions/about-custom-actions#versioning-your-action
```
actions/setup-node@74bc508 # 指向一个 commit
actions/setup-node@v1.0 # 指向一个标签
actions/setup-node@master # 指向一个分支
```
仓库密钥和环境密钥的区别，以及组织密钥

参考：

https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions

仓库密钥：（仓库下面的所有分支和标签可用）
- 仓库密钥是在 GitHub 仓库级别设置的，用于保护仓库的访问权限和敏感信息。
- 仓库密钥可以在仓库的“Settings” > “Secrets” > “Actions”中设置。
- 仓库密钥只能在仓库内使用，不能跨仓库共享。
环境密钥：（可设置哪些分支可用）
- 环境密钥是在 GitHub 分支级别设置的，可以通过设置去设置哪些分支可用
组织密钥：（可以设置哪些仓库可用）

另外，在工作流里面是打印不出来密钥的

构建画爱心为可执行程序

原始代码效果：

代码：

# 版权https://github.com/royalneverwin/beating-heart

from tkinter import * # 导入tkinter库，用于创建GUI界面
from math import sin, cos, pi, log # 导入数学函数，用于心形计算
import random # 导入随机数模块，用于生成随机点
import time # 导入时间模块（当前代码未使用，但保留）

# 定义画布的宽度和高度
CANVAS_WIDTH = 640
CANVAS_HEIGHT = 480
# 计算画布中心坐标
CANVAS_CENTER_X = CANVAS_WIDTH / 2
CANVAS_CENTER_Y = CANVAS_HEIGHT / 2
# 心形放大倍数
IMAGE_ENLARGE = 11


def scatter_inside(x, y, beta=0.15): # 在心形内部生成散点
 """使用对数分布在给定点附近生成内部散点"""
 ratiox = -beta * log(random.random()) # 对数分布计算x方向偏移量，可调整beta值改变分布
 ratioy = -beta * log(random.random()) # 对数分布计算y方向偏移量
 dx = ratiox * (x - CANVAS_CENTER_X) # 计算x方向的实际偏移
 dy = ratioy * (y - CANVAS_CENTER_Y) # 计算y方向的实际偏移
 return x - dx, y - dy # 返回散点的新坐标


def heart_function(t, enlarge_ratio: float = IMAGE_ENLARGE): # 定义心形曲线方程
 """根据参数t生成心形曲线的x,y坐标"""
 # 心形曲线参数方程
 x = 16 * (sin(t)**3)
 y = -(13 * cos(t) - 5 * cos(2*t) - 2 * cos(3*t) - cos(4*t))

 # 放大心形
 x *= enlarge_ratio
 y *= enlarge_ratio

 # 将心形移动到画布中心
 x += CANVAS_CENTER_X
 y += CANVAS_CENTER_Y

 return int(x), int(y) # 返回整数坐标


def shrink(x, y, ratio): # 向心形中心收缩点
 """根据距离中心点的平方反比计算收缩量"""
 sk_range = -1 / ((x - CANVAS_CENTER_X) ** 2 + (y - CANVAS_CENTER_Y) ** 2) # 平方反比因子
 dx = ratio * sk_range * (x - CANVAS_CENTER_X) # x方向收缩量
 dy = ratio * sk_range * (y - CANVAS_CENTER_Y) # y方向收缩量
 return x - dx, y - dy # 返回收缩后的坐标


class Heart:
 def __init__(self, frame): # 初始化心形类
 self.points = set() # 存储心形曲线上的点
 self.edge_points = set() # 存储边缘散点
 self.inside_points = set() # 存储内部散点
 self.all_points = {} # 存储每一帧的所有点坐标
 self.build(2000) # 构建初始点集，可调整点的数量
 self.frame = frame # 动画的总帧数
 for f in range(frame): # 预计算每一帧的点位置
 self.calc(f)
 self.random_halo = 1000 # 用于光晕效果的随机点数量（未直接使用）

 def build(self, number): # 生成初始点集
 """在心形上生成随机点及其边缘和内部散点"""
 # 在心形曲线上随机生成number个点
 for _ in range(number):
 t = random.uniform(0, 2 * pi) # 随机生成角度t
 x, y = heart_function(t) # 计算心形上的点
 x, y = shrink(x, y, -1000) # 向中心收缩点
 self.points.add((int(x), int(y))) # 添加到点集

 # 生成边缘散点
 for px, py in self.points:
 for _ in range(3): # 每个点生成3个边缘散点，可调整数量
 x, y = scatter_inside(px, py, 0.05) # 在点附近生成散点，可调整beta值
 self.edge_points.add((x, y)) # 添加到边缘点集

 # 生成内部散点
 pt_ls = list(self.points) # 将点集转为列表以便随机选择
 for _ in range(4000): # 生成4000个内部散点，可调整数量
 x, y = random.choice(pt_ls) # 随机选择一个基础点
 x, y = scatter_inside(x, y) # 在其附近生成散点
 self.inside_points.add((x, y)) # 添加到内部点集

 def cal_position(self, x, y, ratio): # 计算点在跳动时的位置
 """根据距离中心的平方反比计算跳动幅度"""
 bt_range = 1 / ((x - CANVAS_CENTER_X) ** 2 + (y - CANVAS_CENTER_Y) ** 2) # 跳动因子
 dx = ratio * bt_range * (x - CANVAS_CENTER_X) + random.randint(-1, 1) # x方向位移
 dy = ratio * bt_range * (y - CANVAS_CENTER_Y) + random.randint(-1, 1) # y方向位移
 return x - dx, y - dy # 返回跳动后的位置

 def calc(self, frame): # 计算每一帧的点位置
 """预计算每帧中所有点的动态位置"""
 ratio = 800 * sin(frame / 10 * pi) # 跳动幅度随正弦变化，30fps，可调整
 all_pts = [] # 存储当前帧所有点的列表

 # 生成光晕效果
 halo_radius = int(4 + 6 * (1 + sin(self.frame / 10 * pi))) # 光晕半径随时间变化
 halo_number = int(3000 + 4000 * abs(sin(self.frame / 10 * pi) ** 2)) # 光晕点数量
 heart_halo_point = set() # 存储光晕点
 for _ in range(halo_number):
 t = random.uniform(0, 2 * pi) # 随机角度
 x, y = heart_function(t, enlarge_ratio=11.6) # 生成光晕基础点
 x, y = shrink(x, y, halo_radius) # 向中心收缩
 if (x, y) not in heart_halo_point: # 避免重复
 heart_halo_point.add((x, y))
 x += random.randint(-14, 14) # 添加随机偏移
 y += random.randint(-14, 14)
 size = random.choice((1, 2, 2)) # 随机选择点大小
 all_pts.append((x, y, size)) # 添加到点列表

 # 计算心形曲线上的点
 for x, y in self.points:
 x, y = self.cal_position(x, y, ratio) # 计算跳动位置
 size = random.randint(1, 3) # 随机点大小，可调整
 all_pts.append((x, y, size))

 # 计算边缘点
 for x, y in self.edge_points:
 x, y = self.cal_position(x, y, ratio)
 size = random.randint(1, 2) # 随机点大小，可调整
 all_pts.append((x, y, size))

 # 计算内部点
 for x, y in self.inside_points:
 x, y = self.cal_position(x, y, ratio)
 size = random.randint(1, 2) # 随机点大小，可调整
 all_pts.append((x, y, size))

 self.all_points[frame] = all_pts # 保存当前帧的点数据

 def render(self, canvas, frame): # 渲染点到画布上
 """在画布上绘制当前帧的所有点"""
 for x, y, size in self.all_points[frame % self.frame]: # 循环取帧数据
 # 绘制矩形点，颜色为粉红色
 canvas.create_rectangle(x, y, x+size, y+size, width=0, fill='#ff7171')


def draw(root: Tk, canvas: Canvas, heart: Heart, frame=0): # 动画绘制函数
 """递归调用实现心形跳动动画"""
 canvas.delete('all') # 清空画布
 heart.render(canvas, frame) # 绘制当前帧
 # 每30毫秒刷新一次，相当于约33fps
 root.after(30, draw, root, canvas, heart, frame+1)


if __name__ == '__main__': # 主程序入口
 root = Tk() # 创建主窗口
 root.title('漂亮宝贝一周年快乐') # 设置窗口标题
 # 创建画布，背景黑色
 canvas = Canvas(root, bg='black', height=CANVAS_HEIGHT, width=CANVAS_WIDTH)
 canvas.pack() # 将画布添加到窗口
 heart = Heart(20) # 创建心形对象，帧数设为20
 draw(root, canvas, heart) # 开始动画
 root.mainloop() # 进入主循环，显示窗口

然后创建一个.github/workflows文件夹，并在其中创建一个love_heart.yml文件。文件内容如下填写,功能是创建一个windows的可执行程序

# This workflow will install Python dependencies, run tests and lint with a single version of Python
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
# 这是一个 GitHub Actions 工作流，用于安装 Python 依赖、运行测试和代码检查，使用单一 Python 版本
# 更多信息请参考上述 GitHub 文档链接

name: 画爱心Windows版  # 工作流名称，显示在 GitHub Actions 界面上，表示这是一个在 Windows 上构建“画爱心”程序的工作流

on: # 定义触发工作流的事件
 workflow_dispatch: # 手动触发事件，允许用户通过 GitHub 界面手动运行此工作流

permissions: # 设置工作流的权限
 contents: read  # 授予读取仓库内容的权限，确保工作流可以访问代码

jobs: # 定义工作流中的任务
 pyinstaller-build: # 任务名称，表示使用 PyInstaller 构建可执行文件
 runs-on: windows-latest  # 指定运行环境为最新的 Windows 系统
 steps: # 定义任务的具体步骤
 - name: Create Executable  # 步骤名称，表示创建可执行文件
 uses: sayyid5416/pyinstaller@v1  # 使用社区提供的 PyInstaller Action，版本为 v1
 with: # 配置 Action 的参数
 python_ver: '3.12' # 指定使用的 Python 版本为 3.12
 spec: 'love_heart.py' # 指定 PyInstaller 的构建配置文件或主 Python 文件为 love_heart.py
 upload_exe_with_name: 'love_heart' # 指定上传的可执行文件名称为 love_heart
 options: --onefile, --name "love_heart", --windowed,  # PyInstaller 的构建选项
 # --onefile: 将所有内容打包为单个可执行文件（生成 .exe 文件）
 # --name "love_heart": 设置输出可执行文件的名称为 love_heart（最终为 love_heart.exe）
 # --windowed: 生成无控制台窗口的 GUI 应用程序，适合 Windows 上的图形界面程序
 # 注意：选项之间用逗号分隔，最后一个选项后不需要逗号，但此处保留原始格式

快速入门教程

目标

创建一个简单的 GitHub Actions 工作流，在每次推送代码时运行一个脚本，输出 “Hello, GitHub Actions!"。

步骤

创建仓库
在 GitHub 上创建一个新仓库（或使用现有仓库）。
添加工作流文件
- 在仓库根目录下创建文件夹 .github/workflows。
- 在该文件夹中创建一个文件，例如 hello.yml。

编写工作流文件
将以下内容写入 hello.yml：

name: Hello World Workflow

# 触发条件：在推送代码到 main 分支时运行
on:
 push:
 branches:
 - main

# 定义任务
jobs:
 say-hello:
 runs-on: ubuntu-latest # 使用 GitHub 提供的最新 Ubuntu 虚拟机
 steps:
 - name: Checkout code
 uses: actions/checkout@v3 # 检出代码到虚拟机

 - name: Say Hello
 run: echo "Hello, GitHub Actions!" # 运行简单的 shell 命令

提交文件
将 hello.yml 提交到仓库的 main 分支。
查看运行结果
- 转到仓库的 Actions 标签页。
- 你会看到名为 “Hello World Workflow” 的工作流正在运行。
- 点击工作流名称，查看日志，确认 “Hello, GitHub Actions!” 已输出。

进阶示例

运行测试并部署

假设你有一个 Node.js 项目，想在推送代码时运行测试并部署到服务器。

工作流文件示例
创建 .github/workflows/test-and-deploy.yml：

name: Test and Deploy

on:
 push:
 branches:
 - main

jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout code
 uses: actions/checkout@v3

 - name: Setup Node.js
 uses: actions/setup-node@v3
 with:
 node-version: '16'

 - name: Install dependencies
 run: npm install

 - name: Run tests
 run: npm test

 deploy:
 needs: test # 在 test 任务成功后运行
 runs-on: ubuntu-latest
 steps:
 - name: Checkout code
 uses: actions/checkout@v3

 - name: Deploy to server
 run: |
 echo "Deploying to server..."
 # 这里可以添加实际部署命令，例如通过 SSH

添加秘密（Secrets）
如果部署需要敏感信息（如 SSH 密钥）：
- 转到仓库的 Settings > Secrets and variables > Actions。
- 点击 New repository secret，添加密钥（如 SSH_KEY）。
- 在工作流中通过 secrets.SSH_KEY 使用它。

常用配置

触发事件

on:
 push: # 推送时触发
 branches:
 - main
 pull_request: # 拉取请求时触发
 branches:
 - main
 schedule: # 定时触发（每天凌晨0点）
 - cron: '0 0 * * *'

设置环境变量

env:
 MY_VAR: "Hello"
jobs:
 example:
 runs-on: ubuntu-latest
 steps:
 - run: echo $MY_VAR # 输出 "Hello"

使用社区 Action
示例：使用 actions/cache 缓存依赖：

- name: Cache node modules
 uses: actions/cache@v3
 with:
 path: ~/.npm
 key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

调试技巧

查看日志：在 Actions 标签页点击工作流，展开每个 Job 和 Step 查看详细输出。
添加调试步骤：在步骤中运行 ls -la（Linux）或 dir（Windows）检查文件。
使用 GitHub 提供的测试工具：在本地安装 act（需要 Docker）模拟运行工作流。

常见问题

工作流没触发？
检查 on 配置是否匹配事件和分支。
权限不足？
在仓库设置中确认 Actions 已启用（Settings > Actions > General）。
需要更多计算资源？
考虑使用自托管 Runner。

扩展阅读

官方文档：https://docs.github.com/en/actions
社区 Actions：https://github.com/marketplace?type=actions

on字段

在 GitHub Actions 的 on 字段中，你可以定义触发工作流的事件。workflow_dispatch 是其中一种触发方式，表示手动触发。除了 workflow_dispatch，还有许多其他触发事件可以选择，具体取决于你的需求。以下是 on 可以填写的参数（触发事件类型），以及它们的用途和可能配置项：

`on` 可填写的触发事件类型

1. `workflow_dispatch`（手动触发）

作用：允许用户通过 GitHub 界面手动触发工作流。
可选配置：
- inputs：定义手动触发时可以输入的参数。

示例：

on:
 workflow_dispatch:
 inputs:
 name:
 description: '输入你的名字'
 required: true # 是否必填
 default: 'Anonymous' # 默认值
 version:
 description: '选择版本'
 type: choice  # 类型可以是 string, boolean, choice 等
 options:
 - 'v1'
 - 'v2'
 required: false

用途：适合需要用户干预或自定义参数的场景，例如手动选择构建版本。

2. `push`（推送事件）

作用：当代码被推送到指定分支或路径时触发。
可选配置：
- branches：指定触发分支。
- branches-ignore：忽略特定分支。
- paths：指定触发文件路径。
- paths-ignore：忽略特定文件路径。
- tags：指定触发标签。

示例：

on:
 push:
 branches:
 - main
 - 'feature/*' # 支持通配符
 paths:
 - 'src/**' # 只在 src 目录下文件变更时触发
 tags:
 - 'v*'

用途：适合每次代码提交时自动构建或测试。

3. `pull_request`（拉取请求事件）

作用：当拉取请求（PR）被创建、更新或合并时触发。
可选配置：
- branches：目标分支。
- types：触发的事件类型（如 opened, synchronize, closed）。
- paths：触发文件路径。

示例：

on:
 pull_request:
 branches:
 - main
 types:
 - opened  # PR 创建时触发
 - synchronize  # PR 更新时触发
 paths:
 - '*.py' # 只在 Python 文件变更时触发

用途：用于 PR 的自动化检查或构建。

4. `schedule`（定时触发）

作用：按计划时间触发，使用 cron 表达式。
可选配置：
- cron：定义运行时间（UTC）。

示例：

on:
 schedule:
 - cron: '0 0 * * *' # 每天 UTC 00:00 触发
 - cron: '*/15 * * * *' # 每 15 分钟触发一次

用途：适合定时任务，例如每天构建或检查。

5. `release`（发布事件）

作用：当 GitHub 发布（release）相关操作发生时触发。
可选配置：
- types：触发类型（如 published, created, edited）。

示例：

on:
 release:
 types:
 - published  # 发布时触发
 - prereleased  # 预发布时触发

用途：用于发布版本时的自动化构建或部署。

6. `issues`（问题事件）

作用：当 GitHub Issues 相关操作发生时触发。
可选配置：
- types：触发类型（如 opened, closed, labeled）。

示例：

on:
 issues:
 types:
 - opened  # 新建 issue 时触发
 - labeled  # 添加标签时触发

用途：适合与问题管理相关的自动化任务。

7. `workflow_run`（工作流运行事件）

作用：当另一个工作流完成时触发当前工作流。
可选配置：
- workflows：指定监听的工作流名称。
- types：触发类型（如 completed）。
- branches：触发分支。

示例：

on:
 workflow_run:
 workflows: ['Build'] # 监听名为 Build 的工作流
 types:
 - completed  # Build 完成后触发
 branches:
 - main

用途：用于工作流间的依赖关系，例如先构建再部署。

8. 其他事件

create：当创建分支或标签时触发。
```
on:
 create:
 branches:
 - 'feature/*'
```
delete：当删除分支或标签时触发。
fork：当仓库被 fork 时触发。

watch：当用户点击“Star”时触发。

on:
 watch:
 types:
 - started  # 用户 star 仓库时触发

组合使用

你可以组合多个事件类型。例如：

on:
 push:
 branches:
 - main
 pull_request:
 branches:
 - main
 workflow_dispatch:

这样，工作流会在推送、拉取请求或手动触发时运行。

参数总结表

触发事件	主要配置项	示例用途
`workflow_dispatch`	`inputs`	手动构建，带自定义参数
`push`	`branches`, `paths`, `tags`	代码提交时构建
`pull_request`	`branches`, `types`, `paths`	PR 检查
`schedule`	`cron`	定时任务
`release`	`types`	发布版本
`issues`	`types`	Issue 管理
`workflow_run`	`workflows`, `types`, `branches`	工作流依赖
`create`	`branches`	创建分支或标签

针对你的需求

你的工作流目前使用 workflow_dispatch，适合手动触发构建“画爱心”程序。如果需要其他触发方式：

自动构建：用 push 或 pull_request，在代码变更时触发。
定时构建：用 schedule，每天生成新版本。
发布版本：用 release，在发布时生成可执行文件。

如果你想具体调整（例如添加 push 或 schedule），可以告诉我，我帮你写出对应配置！

VScode使用教程|cursor使用教程

Mon, 03 Mar 2025 00:00:00 +0800

参考： https://blog.csdn.net/weixin_46474921/article/details/132841711

安装及设置

1. 下载安装

VScode官网注意，这一步最好全部打勾

2. 设置默认terminal为cmd

自动fetch远程分支

Git 默认不会自动从远程拉取状态更新。只有当你显式运行 git fetch 或 git pull 时，本地仓库才会更新远程分支引用。如果你希望在 VS Code / Cursor 中自动感知远程分支变化，需要开启自动 fetch：

设置路径：Settings → 搜索 git.autofetch → 勾选启用

建议同时设置自动 fetch 间隔（默认 3 分钟）：

{
 "git.autofetch": true,
 "git.autofetchPeriod": 180
}

注意：如果仓库的 remote 名不是默认的 origin，VS Code 的 Git 插件和 GitHub Pull Requests 插件可能无法正确识别上下文。需要在 settings.json 中显式配置：

{
 "githubPullRequests.remotes": ["zata", "origin", "upstream"]
}

配置完成后执行 Cmd+Shift+P → Developer: Reload Window 生效。

设置文件自动保存

vscode右侧的预览窗口设置

设置方法，在设置里面搜索minimap

vscode写markdown插入图片时放在指定目录

参考 https://juejin.cn/post/7244809769794289721

打开粘贴选项

**/*.md images/${documentDirName}/${fileName} # 以原始文件名放到 ./assets/<md文件名>/<图片文件名>
**/*.md images/${documentBaseName}/${documentBaseName}.${fileExtName} # 重新以md文件名命名图片名
**/*.md images/${documentBaseName}/image.${fileExtName} # 以image.png重命名放到images/文件名 文件夹下

vscode折叠代码 ctrl+k ctrl+0

Diff Editor settings

取消相同的代码被折叠

diff 双栏变一栏

vscode 插件

GitLG
Office Viewer
Markdown Preview Mermaid Support

GitLG
office viewer

但是有一个非常严重的问题，就是说如果安装了office viewer 会导致vscode自己的image paste失效

不过我发现一个解决方案，就是改下配置，然后不要用ctrl+v粘贴，而是用鼠标右键然后paste

当然，如果想支持更多办公文档的查看，那么可以一步到位，直接安装office viewer(Markdown Editor)。但这个插件有一个坑点，就是会更改markdown文件的格式，所以安装之后，可以取消对markdown文件的默认开启方式。方法很简单，只需右键单击一个markdown文件，选择打开方式，在命令栏中选择最下面的为*.md配置默认编辑器，最后点击文本编辑器就可以了。

此外，这个插件内嵌了一个主题，所以安装之后界面的颜色可能会发生变化，不必惊慌，重新选择一个主题就可以了。

Markdown Preview Mermaid Support（作者：Matt Bierner）特点：这是下载量最高、最基础的 Mermaid 插件。安装后，它会无缝集成到 VS Code 原生的 Markdown 预览功能中。用法：在 .md 文件中输入 ```mermaid 代码块，然后点击 VS Code 右上角的“预览”按钮（或快捷键 Ctrl+Shift+V / Cmd+Shift+V），就能直接在右侧看到渲染出的图表。

遇到的问题和解决方案

vscode 一直 reactivatiing terminals

这个是由于python扩展找不到虚拟环境的问题，具体可以看 https://stackoverflow.com/questions/78886125/vscode-python-extension-loading-forever-saying-reactivating-terminals/78886126#78886126

我的解决方法是把python Locator换成js

安装工具包之后，桌面cmd窗口可用，但是vscode/cursor不可用

cmd加载成功，但是 cursor ternimal没有生效。解决办法：完全退出cursor，然后重启cursor

GitHub Pull Requests 插件一直 Loading

现象：安装 GitHub Pull Requests and Issues 插件后，VS Code 侧边栏一直处于 loading 状态，无法正常显示当前仓库的 PR。

优先检查三个点：

git remote -v
gh auth status
gh pr list --repo OWNER/REPO --state all --limit 10

这次遇到的原因是仓库 remote 名不是默认的 origin，而是自定义的 zata。VS Code 的 GitHub PR 插件默认主要识别 origin 和 upstream，如果仓库使用了其他 remote 名，插件可能找不到 GitHub 仓库上下文，于是一直 loading。

解决方法：在 VS Code 的 settings.json 中显式配置插件要识别的 remote 名：

"githubPullRequests.remotes": [
 "zata",
 "origin",
 "upstream"
]

然后执行：

Cmd+Shift+P
Developer: Reload Window

如果还是 loading，打开下面这个输出面板看具体报错：

View -> Output -> GitHub Pull Requests

另外要注意：如果 PR 已经 merge，插件的 open PR 列表里可能不会显示。可以用命令确认：

gh pr list --repo OWNER/REPO --state all --limit 10
gh pr view PR_NUMBER --repo OWNER/REPO

macOS 下按 Cmd+Q 直接退出 VSCode

在 macOS 上使用 VSCode / Cursor 时, 按下 Cmd+Q 会触发 macOS 的"退出应用"快捷键, 直接把整个 VSCode 进程关掉 (而不是仅关闭当前窗口), 容易丢失未保存的内容。

解决方法是在 VSCode 的快捷键设置里把 Cmd+Q 绑定的命令移除或改成无害操作:

打开 Cmd+K Cmd+S (Keyboard Shortcuts) 或者 File → Preferences → Keyboard Shortcuts。
搜索 cmd+q 或 Quit, 找到 Quit / workbench.action.quit 这一项。
双击该项, 选择 Remove Keybinding (删除快捷键), 或者改成 Cmd+Q 之外的其他组合 (比如改成 Cmd+Shift+Q 之类的)。

也可以直接编辑 keybindings.json (命令面板 Preferences: Open Keyboard Shortcuts (JSON)), 写入:

[
 {
 "key": "cmd+q",
 "command": "-workbench.action.quit"
 }
]

加负号 - 表示解除该命令的快捷键绑定。保存后重启 VSCode 生效, 此后按 Cmd+Q 不会再退出 VSCode, 只会由 macOS 提示要不要退出 (或者完全没反应), 避免误触丢工作内容。

git&github_tutorial

Fri, 28 Feb 2025 00:00:00 +0000

Git 基础操作
远程仓库操作
- git clone 远程项目,同步远程项目更新
- git 版本标签
分支与合并
版本回退与撤销
GitHub 相关
身份验证
问题解决
实战
- Git 项目依赖管理：Submodule 与 Subtree 实战教程
- 如何将 clone 下来的项目推送到自己的新仓库并同步原始仓库更新

git基本使用

安装

windows 安装

简单常用命令


%%设置用户签名%%
git config --global user.name [username]
git config --global user.email [useremail]

%%设置对于非ASCII字符的显示方式%%
git config--global core.quotepath false

%%设置init分支名%%
git config --global init.defaultBranch main

git branch --set-upstream-to=origin/<远程分支> <本地分支> # 绑定本地分支和远程分支

# 设置 HTTP/HTTPS 代理
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# 或者设置 SOCKS5 代理（更稳定）
git config --global http.proxy socks5://127.0.0.1:7890

git pull --rebase # 变基拉取


git stash push --keep-index #只 stash 未暂存但已跟踪的修改 加-u 参数同时 stash 未跟踪文件

git stash pop # 恢复被 stash 的未暂存部分
# 或
git stash apply

git remote prune <remote-name> # 清理本地仓库中对远程仓库 zata 已删除分支的过时跟踪引用。 并不是删除分支


git gc --prune=now #清理不必要的文件并优化本地仓库


%% 设置远端库别名
git remote add <别名> <网址>

%% 查看远端库
git remote -v

%%获取远程仓库的所有更新，并删除本地已经不存在的远程分支的跟踪引用，以保持本地仓库与远程仓库的同步
git fetch --prune

%%查看本地库状态%%
git status

%%追踪文件，放入暂存区%%
git add [filename]
git add . #所有文件放入暂存区
%%撤销追踪%%
git restore 【file】

%%删除暂存区的文件%%
git rm --cache 【filename】

%%提交本地库%%
git commit -m "[提交信息]" 【文件名（可以不加）】

%%撤销commit提交%%
git reset --soft HEAD


%%推送远程库
git push [<远程主机名>] [<本地分支>:<远程分支>] #如果不加分支对应信息就默认上次记录的全部分支
git push origin $(git branch --show-current) # 将当前分支推送到远程仓库（通常是 `origin`），并保持相同的分支名

%%拉取远程库%%
git pull [<远程主机名>] [<远程分支>:<本地分支>] # 从远程仓库（名为 origin）的 main 分支拉取代码并自动与本地的 main 分支合并 ,如果方括号里面的不加就默认拉去上一次的
git pull [<远程主机名>] --depth <分支深度> [<远程分支>:<本地分支>] # 例如git pull zata --depth 1 hugo:hugo ，用于历史内容过多，只拉取少量历史记录


%%查看引用日志版本信息%%
git reflog
%%查看详细日志%%
git log
%%以图形化方式查看本地和远程分支的结构%%
git fetch origin
git log --graph --oneline --all --remotes

%%版本穿梭%% 一般用soft多一点
git reset --hard 【版本号】


git log --oneline --graph --all # 显示所有分支的提交记录建议直接使用gitG

--.gitignore--------------------
test* 忽略以test开头的文件

一些问题解决

Git Rebase 冲突解决（VS Code） — 20260308

当你执行 git rebase <目标分支> 开始变基后，Git 会尝试将你的提交依次应用到目标分支上。如果在这个过程中发生代码冲突，Git 会自动暂停变基操作，等待你解决冲突。

此时，VS Code 会清晰地提示你当前状态：

文件列表中被检测到冲突的文件旁边会出现警告标记（⚠️）。
编辑器底部状态栏会显示“合并冲突”的提示。

解决冲突的核心步骤分为以下环节：

第一步：打开并处理冲突文件 在编辑器中打开有冲突标记的文件，你会看到类似以下结构的代码块：

<<<<<<< HEAD
这是你当前分支（正在变基的提交）的代码
=======
这是来自目标分支（或历史提交中）的代码
>>>>>>> commit-hash

你需要决定如何整合这些代码。你有两种主要方式来完成这一步：

使用 VS Code 内置工具：直接点击冲突标记区域上方出现的选项按钮。你可以选择“接受当前更改”、“接受传入更改”或“保留双方更改”。如果内置选项不能满足需求，你也可以手动删除所有的 <<<<<<<、======= 和 >>>>>>> 标记，并编辑成你最终想要的代码。
使用 GitLens 扩展：如果你安装了 GitLens 扩展，它会提供更加强大和直观的并排对比视图，方便你逐块检查和解决冲突。

第二步：标记冲突文件为已解决 在完成一个文件的所有冲突编辑后，你需要告诉 Git 这个文件的冲突已经处理完毕。

你可以在 VS Code 的源代码管理侧边栏（√图标）中，找到该文件，点击旁边的“+”号或右键选择“暂存更改”。
或者在终端中执行命令 git add <文件名>。

第三步：继续变基过程 标记完所有已解决的冲突文件后，你需要让 Git 继续执行变基操作。

在 VS Code 中，你可以点击底部状态栏的“继续变基”按钮。
或者在终端中执行命令 git rebase --continue。

随后，Git 会尝试应用下一个提交，你可能需要重复上述步骤来解决后续可能出现的冲突，直到所有提交都应用完成。

其他有用的命令 在变基过程中，你还可以使用以下命令：

git rebase --skip：跳过当前正在应用的提交（请谨慎使用，这意味着完全丢弃这个提交的更改）。
git rebase --abort：完全终止本次变基操作，分支将回退到执行 git rebase 之前的状态。

快速流程总结 一个典型的 rebase 解决冲突流程可以简化为：

git rebase main
# 发生冲突
# 使用 VS Code 编辑文件解决冲突
git add .
git rebase --continue
# 可能重复“编辑->add->continue”直到完成

最后的重要提示

变基过程可能需要解决多个提交引发的冲突，请耐心处理完一个后继续下一个。
随时可以使用 git status 命令来查看当前的变基进度和状态。
在进行变基等重写历史的操作前，创建一个备份分支是一个好习惯：git checkout -b backup-branch。

解决Mac、linux下使用git命令时中文乱码的办法

git config --global core.quotepath false

要将远程仓库的 `other` 分支设置为 `main` 分支，并删除原来的 `main` 分支，可以按照以下步骤操作：

确保本地仓库是最新的 首先，确保你的本地仓库与远程仓库同步，并切换到 other 分支：
```
git fetch origin
git checkout other
git pull origin other
```
将 other 分支推送到远程的 main 分支 使用 git push 的 --force 选项，将 other 分支的内容强制覆盖远程的 main 分支：
```
git push origin other:main --force
```
这会将 other 分支的内容直接推送到远程的 main 分支，覆盖原有的 main 分支。
更新本地仓库 在本地仓库中，确保你的 main 分支与远程的 main 分支同步：
```
git checkout main
git pull origin main
```
删除本地的 other 分支（可选） 如果你不再需要本地的 other 分支，可以删除它：
```
git branch -d other
```
验证操作 确认远程仓库的分支状态：
```
git fetch origin
git branch -r
```
你应该看到 origin/main 包含了 other 分支的内容，且 origin/other 仍然存在（除非你也想删除它）。
（可选）删除远程的 other 分支 如果 other 分支不再需要，可以删除远程的 other 分支：
```
git push origin --delete other
```

使用windows系统服务器做远程开发碰到的问题

使用哪个版本的git

感觉这个没有太大关系，不过后面发现便携版本的git也是可用的，感觉以后可以就使用便携版的，毕竟不需要界面
使用windows远程服务器进行git pull总是卡死

2025年0617，买了一个腾讯云到2h2G服务器，想用来写hugo博客，但是在pull代码的时候总是卡死，试了很多次，我以为是服务器性能太烂了，最后发现，如果使用http地址pull的话就没有问题。但是后面又发现使用github的http地址的话会存在无法push的情况，所以我最终给出的解决方案就是：使用github的http地址拉取项目，然后使用ssh地址同步

如果想要临时查看某次commit时项目的全部代码

git log --oneline
git checkout <commit哈希值> # 查看代码
git checkout main # 返回主分支

在本地开发环境检查远程是否更新

第一种方法

git log --oneline --graph --all

第二种方法

# 设置跟踪远程分支
git branch --set-upstream-to=origin/<branch> <branch> # git branch --set-upstream-to=origin/main main


# 查看是否跟踪
git branch -vv


# 下载数据
git fetch origin

# 查看是否有更新
git status

是否跟踪对比

git clone 远程项目,同步远程项目更新

git fetch origin #查看远程项目更新
git pull origin 远程分支：本地分支

git 版本标签

什么是版本标签？标签（Tag）是 Git 中的一个引用（reference），指向某个特定的提交。它通常用于标记一个稳定的发布版本，比如 v1 表示第一个正式版本。在 GitHub 上，标签还会显示在 Releases 页面，便于用户下载或查看。两种标签类型轻量标签（Lightweight Tag）：只是一个简单的指针，指向某个提交，不包含额外信息。附注标签（Annotated Tag）：包含额外元数据（如创建者、日期、描述），更常用于正式发布。

# 假设你已经完成代码更改并提交
git add .
git commit -m "Finalize version 1.0"

# 创建一个轻量标签（简单标记当前提交）
git tag v1

# 或者创建一个附注标签（带描述信息，推荐用于正式发布）
git tag -a v1 -m "Release version 1.0"

# 查看所有本地标签
git tag

# 推送单个标签到远程仓库（如 GitHub）
git push origin v1

# 或者推送所有标签到远程仓库
git push origin --tags

# （可选）如果需要删除本地标签
git tag -d v1

# （可选）如果需要删除远程标签
git push origin --delete v1

git merge详解

如果没有冲突，Git 会自动完成合并，并创建一个合并提交（merge commit，如果需要的话）。如果有冲突，Git 会暂停合并，提示你解决冲突（后面会讲怎么处理）。

无冲突的合并（Fast-forward）

如果 main 分支没有额外改动，而 feature 分支只是基于 main 增加了提交，Git 会执行"快进合并"（fast-forward）。这时候历史记录会变成一条直线，看起来像是直接在 main 上开发了一样。

有额外提交的合并（Merge Commit）

如果 main 和 feature 都有各自的提交，Git 会创建一个新的合并提交，保留两个分支的历史。命令一样：

git merge <分支名>

但是，合并后，Git 会自动生成一个 Merge commit，这样，从历史上看，分支信息就非常清楚。

冲突的合并当两个分支修改了同一文件的同一部分，Git 无法自动决定用哪个版本，就会报冲突。这时你需要手动解决：

运行 git merge feature 后，Git 会提示冲突文件。打开这些文件，冲突部分会被标记为：

<<<<<<< HEAD
（main 分支的内容）
=======
（feature 分支的内容）
>>>>>>> feature

编辑文件，保留你想要的部分，删除标记。解决完后，标记文件为已解决：“git add "，然后提交：“git commit -m ‘解决冲突’

实用技巧查看合并状态：用 git status 检查当前是否在合并过程中。中止合并：如果合并出了问题，想放弃，可以用：

git merge –abort

指定合并策略：默认情况下 Git 会自动选择合并方式，但你可以用选项调整，比如强制非快进合并：

git merge –no-ff feature

如何解决 “fatal: Need to specify how to reconcile divergent branches” 错误

问题根源：什么是“分支分叉”？

这个错误的核心原因是：您的本地分支和它所跟踪的远程分支，各自都有了新的、对方不知道的提交。

让我们用一个形象的例子来说明：

您和您的同事都在 main 分支上工作。你们最后一次同步时的代码状态是 Commit O。
之后，您在本地写了新功能，并创建了两个提交 A 和 B。
在您提交的这段时间里，您的同事完成了另一个任务，并将他的提交 C 和 D 推送（push）到了远程仓库。

这时，Git 的历史记录就变成了两条独立的路径，即“分叉”了：

A—B <– 您的本地 main 分支

—O—C—D <– 远程 origin/main 分支

当您执行 git pull 时，Git 发现它无法简单地“快进”（Fast-forward）来更新您的代码，因为它不知道应该如何处理这两条分叉的路径。为了避免自动操作可能带来的混乱，新版 Git 强制要求您必须明确告诉它您的合并策略。

二、核心概念：两种合并策略 Merge vs. Rebase

要解决分叉问题，您有两种主要的方法：Merge (合并) 和 Rebase (变基)。

方案 A：临时解决本次问题

您可以只在本次 pull 命令中指定策略。

使用 Rebase (推荐)：
```
git pull --rebase
```
这会用变基的方式拉取并应用远程更新。
使用 Merge：
```
git pull --no-rebase # 或者 git pull --merge
```
这会用传统合并的方式，并生成一个合并提交。

方案 B：永久配置默认行为 (一劳永逸)

为了避免每次都输入额外参数，您可以为 Git 设置一个全局的默认 pull 行为。

将 Rebase 设置为默认 (推荐)：

如果您喜欢干净的线性历史，这是大多数现代开发者的首选。
```
git config --global pull.rebase true
```
将 Merge 设置为默认：

如果您偏爱保留所有合并痕迹的传统方式。
```
git config --global pull.rebase false
```
更严格的 ff-only 策略：

还有一个选项是 fast-forward only。
```
git config --global pull.ff only
```
这个设置意味着，只有当您的本地分支没有任何新提交时（即可以“快进”时），git pull 才能成功。如果分支出现分叉，pull 会直接失败，强制您手动执行 git rebase 或 git merge，让您对每一次合并操作都更加谨慎。

|git pull|merge| git 多人协作的时候怎么解决冲突？

使用git-pull 然后git-commit 最后git-push

如果有冲突可以看get merge使用

使用rebase调换最后两个Commit的顺序


# Git 教程：使用 rebase 调换最后两个 Commit 的顺序



本教程将指导你如何使用 `git rebase -i`（交互式 rebase）来调换你本地最后两个 commit 的顺序。## 场景



你通过 `rebase` 将你的本地修改放在了远程分支的最新 commit 之上，但你现在希望反过来，让你自己的修改在前面，让远程的 commit 成为最后一个。**你当前的状态 (HEAD 指向你的修改):**

... -> 远程的最后一个commit -> 你的本地修改 (HEAD)



**你希望达到的状态 (HEAD 指向远程的 commit):**

... -> 你的本地修改 -> 远程的最后一个commit (HEAD)



---



## ⚠️ 重要警告



此操作会**重写 Git 历史**。



**请只在尚未将这些 commit 推送（push）到远程仓库时执行此操作。**

如果你已经推送了 `你的本地修改`，强行修改历史（`git push --force`）会给你的协作者带来严重问题。



---



## 操作步骤



### 步骤 1: 启动交互式 Rebase



你需要编辑最后两个 commit。运行以下命令来启动交互式 rebase，`HEAD~2` 表示“从 HEAD 开始往前数 2 个 commit”。



```bash

git rebase -i HEAD~2

步骤 2: 在编辑器中编辑 Rebase 列表

运行上述命令后，Git 会打开你的默认文本编辑器，显示一个列表。这个列表的顺序是从旧到新（从上到下）。

它看起来会是这样：

pick <hash_A> 远程的最后一个commit 的消息

pick <hash_B> 你的本地修改 的消息



# Rebase ...

# Commands:

# p, pick <commit> = use commit

# ...

pick <hash_A> 是那个较旧的 commit（远程的 commit）。

pick <hash_B> 是那个较新的 commit（你的本地修改）。

步骤 3: 调换 Commit 顺序

你只需要在编辑器中交换这两行的文本顺序，把你的本地修改放到上面（即让它更早发生）：

修改为：

pick <hash_B> 你的本地修改 的消息

pick <hash_A> 远程的最后一个commit 的消息

步骤 4: 保存并退出编辑器

保存文件并关闭编辑器。Git 会立即按照你指定的新顺序重新应用这两个 commit。

步骤 5: 验证结果

操作完成后，你可以使用 git log 来检查历史记录，确认顺序已经被正确调换。

Bash



# 查看最后两个 commit

git log --oneline -2

你现在应该会看到 远程的最后一个commit 的消息 在最上面（最新）的位置。

附录：如何在编辑器中快速调换行顺序

在步骤 3 中，你不需要手动剪切和粘贴。几乎所有编辑器都支持“移动当前行”的快捷键（将光标放在该行任意位置即可）。

常用 GUI 编辑器

Visual Studio Code (VS Code):

Windows / Linux: Alt + ↑ (上移) / Alt + ↓ (下移)

macOS: Option + ↑ (上移) / Option + ↓ (下移)

Sublime Text:

Windows / Linux: Ctrl + Shift + ↑ (上移) / Ctrl + Shift + ↓ (下移)

macOS: Cmd + Ctrl + ↑ (上移) / Cmd + Ctrl + ↓ (下移)

Notepad++:

Ctrl + Shift + ↑ (上移) / Ctrl + Shift + ↓ (下移)

常用终端编辑器 (Git 默认)

Vim / Vi (最常见的默认编辑器):

按 Esc 键确保你处于普通模式 (Normal Mode)。

将光标移动到你想移动的行。

输入 ddp：dd (剪切当前行) + p (粘贴到下一行)，效果是与下一行交换。

输入 ddkP：dd (剪切) + k (上移) + P (粘贴到上一行)，效果是与上一行交换。

(在你的场景中，光标在第二行 pick <hash_B> ... 上时，按 ddkP 即可)

Nano (较简单的编辑器):

Nano 没有直接的“移动行”快捷键，你必须使用剪切和粘贴：

将光标放在要移动的行上。

按 Ctrl + K (剪切该行)。

将光标移动到目标位置（例如，移动到第一行）。

按 Ctrl + U (粘贴该行)。

|公式 | github | github不显示md文件中的公式

第一种方法：使用github推荐的公式写法（推荐） 在写md的时候，使用

$` 和 `$

来包围行内公式

```math
和
 ```

来包围单行公式，如下

第二种方法：插件

但是还是会有一部分显示不正确

解决方法：安装插件：https://chrome.google.com/webstore/detail/mathjax-plugin-for-github/ioemnmodlmafdkllaclgeombjnmnbima/related

git 使用ssh密钥登录github

注意一个密钥只能登录一个github，如果你想要在新的github账户上面添加旧的ssh密钥，就会报错 准备工作：本地先下载安装好git，注册并登陆github账号在注册好后的github账号中先创建一个仓库在本地git创建SSH key 第一步：设置全局的用户名和邮箱（这样主要是不用总是重填）

git config --global user.name '用户名' // 切换到你的github用户名上
git config --global user.email 'github账号注册用的邮箱'

第二步：生成密钥，有可能提示没有这个库，需要安装一下，去搜索一下

ssh-keygen -t rsa -C "你的邮箱地址"

第三步：查看自己本地的密钥，执行以下命令

ls -al ~/.ssh // 查看本机是否有秘钥文件 没有秘钥文件生成秘钥文件
cd ~/.ssh
ls // 查看 .ssh 中有什么文件
cat id_rsa.pub // 查看本地的公钥
cat id_rsa // 查看本地的私钥
（如果是windows系统可以直接到C盘的对应用户名文件夹下的.ssh文件夹中查看）

第四步：将公钥复制粘贴到github上

github上点击头像，点击Settings，进入后点击 SSH and GPS keys，接着点击 New SSH key 将公钥粘贴在key输入框那里，Title则随便输入可以就行

`git 使用token登录github 并拉取项目` （如果电脑上已经登录过了，需要把账户信息清除掉。如果是用ssh密钥登录的也不行，清除token账户信息请看下面"清除电脑上已经登录的github账户信息”）

图1 打开设置	图2 开发者设置	图3 点击Token
图4 生成classic Token	图5 设置命名和权限

最后一步： 在新设备上pull或者push的时候，会让你登录，有两种方式，一种是账号密码，另一种就算token，选择token，然后粘贴上一步生成的token就可以了

github 要求2FA认证

今天上线的时候突然发现，github要求我设置2FA认证，不然就不能登录，手机号我必然是没有的，只能用安全密钥控制具体的github说明在这里：https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication

一句话说，就是需要用TOPT密钥管理工具生成动态密码，然后输入动态密码登录，然后第一次登录会给你一个github-recovery-codes.txt,如果更换设备需要使用这个恢复码登录新设备，然后登录新设备之后也是会给你一个新的恢复码

如果是第一次登录，看到github要求进行2FA，可以安装如下 chrome插件：Github 2FA（去chrome商店搜索）

然后你回到github页面刷新，在上面图片红框的那个位置就会出现一个30s的密码，输入就可以确认，确认好之后会让你下周恢复密钥，记得下载保存

github 清除电脑上已经登录的github账户信息

step1：进入控制面板点击用户账户

step2：管理windows凭证

step3：删除github相关的凭证

git config –global –add safe.directory 设置安全目录

命令用途 git config --global --add safe.directory 命令用于将指定的目录添加到 Git 的安全目录列表中，解决 Git 安全机制导致的仓库访问问题。

问题背景从 Git 2.35.2 开始，Git 引入了更严格的安全机制，默认情况下会拒绝访问由其他用户拥有的目录中的 Git 仓库。这通常发生在以下情况：

在 WSL (Windows Subsystem for Linux) 环境中
在共享目录或挂载的目录中
在 Docker 容器中访问宿主机目录
在多用户系统中

命令语法

git config --global --add safe.directory <directory-path>

使用示例

# 添加单个目录到安全目录列表
git config --global --add safe.directory /code/GRT

# 添加当前目录到安全目录列表
git config --global --add safe.directory "$(pwd)"

# 添加多个目录
git config --global --add safe.directory /path/to/repo1
git config --global --add safe.directory /path/to/repo2

查看当前安全目录列表

# 查看所有安全目录
git config --global --get-all safe.directory

# 查看所有全局配置
git config --global --list | grep safe.directory

删除安全目录

# 删除特定的安全目录
git config --global --unset-all safe.directory /code/GRT

# 删除所有安全目录配置
git config --global --unset-all safe.directory

常见错误信息当遇到安全目录问题时，Git 会显示类似以下的错误：

fatal: detected dubious ownership in repository at '/code/GRT'
To add an exception for this directory, call:
 git config --global --add safe.directory /code/GRT

安全注意事项

谨慎添加目录：只添加你信任的目录，避免添加系统关键目录
使用绝对路径：建议使用绝对路径而不是相对路径
定期检查：定期检查安全目录列表，删除不再需要的目录
环境隔离：在不同环境中使用不同的安全目录配置

替代方案如果不想使用全局配置，也可以：

使用本地配置：在特定仓库中使用 --local 而不是 --global
修改目录权限：确保目录的所有权正确
使用 Git 环境变量：设置 GIT_SAFE_DIRECTORIES 环境变量

验证配置配置完成后，可以验证是否生效：

# 进入目标目录
cd /code/GRT

# 尝试执行 Git 命令
git status

# 如果没有错误信息，说明配置成功

GitHub 分支保护规则（Rulesets）配置

在团队协作中，保护主分支（如 main）是非常重要的一项最佳实践。GitHub 提供了 Rulesets（规则集）功能，可以灵活地配置分支保护策略，而无需启用组织级别的付费功能。

下面介绍两种常见的配置方案：

方案一：极简保护（防删 + 防强制推送）

适用于个人仓库或小型项目，仅开启最核心的两项保护：

Restrict deletions — 限制删除匹配的分支，防止误删主分支。
Block force pushes — 阻止强制推送，避免历史被覆盖。

配置截图如下：

方案二：严格保护（推荐用于团队项目）

适用于多人协作的项目，要求更规范的代码合入流程：

Restrict deletions — 限制删除分支。
Require a pull request before merging — 必须通过 Pull Request 才能合并代码。
Require status checks to pass — 要求指定的 CI 检查通过后才能合并。例如：
- Python Quality Gate
- Frontend Build
Block force pushes — 阻止强制推送。

配置截图如下：

提示：Rulesets 对私有仓库完全免费即可使用。对于团队项目，建议至少开启「Require a pull request before merging」和「Require status checks to pass」，以保证代码质量和审计追踪。

`git clone 出现以下问题：fatal: unable to access XXX: gnutls_handshake() failed: The TLS connection was non-properly terminated.`

git clone 出现以下问题：fatal: unable to access 'https://github.com/QwenLM/Qwen.git/': gnutls_handshake() failed: The TLS connection was non-properly terminated.

可以参考stack overflow里面的Stack 我是执行下面两行代码解决（ubuntu系统）

apt-get update
apt-get install curl

`[git push] ssh: connect to host github.com port 22: Connection timed out fatal: Could not....`

最有可能是防火墙问题，可以参考github官方的解决方法用443端口解决 https://docs.github.com/en/authentication/troubleshooting-ssh/using-ssh-over-the-https-port

第一步,用以下代码测试443端口是否可用

ssh -T -p 443 git@ssh.github.com

如果出现这样就是可用的，那么恭喜，十拿九稳了！用如下ssh地址替代原来的

git clone ssh://git@ssh.github.com:443/YOUR-USERNAME/YOUR-REPOSITORY.git

注意是替代，直接用原来的地址加端口是不行的。

拿下！

`远程分支是v3版本，本地的v2版本，但是本地修改了文件还没有add也没有commit，应该怎么更新本地？`

1. 第一步：首先保存你的本地修改：

git stash

这会将你当前的修改暂时保存起来

2. 第二步：拉取远程更新

git fetch origin

3. 第三步：更新本地分支到远程版本

git merge FETCH_HEAD

4. 第四步，恢复你之前的本地修改

cpp git stash pop

5. 如果在恢复 stash 时遇到冲突，你需要手动解决这些冲突。解决完冲突后，你可以:

添加解决冲突后的文件 git add .

提交你的修改 git commit -m “your commit message”

提示：

如果你想在应用 stash 前查看保存了什么内容，可以用 git stash list 查看 stash 列表如果你想查看具体改动，可以用 git stash show -p 如果合并时遇到问题，随时可以用 git status 查看当前状态如果想放弃当前操作回到起点，可以用 git reset –hard HEAD（注意这会丢失未提交的修改）

用githooks解决github大文件报错100M限制或50M限制-大文件-50M-githooks-git

如果你已经commit了大文件，并且报错了，可以使用下面方法，基本上都起作用

apt-get install git-filter-repo

# 删除指定的大文件（路径必须完全匹配）
git filter-repo --path "路径地址" --invert-paths

如果还没有提交

# 1. 把大文件取消追踪
git rm --cached "path/to/large/file" # 引号括起来的是大文件地址
# 2. 把大文件加入.gitignore
echo "path/to/large/file" >> .gitignore
# 3. 更改提交 （当然不commit直接git push XXX 也是可以的）
git add .gitignore
git commit -m "Update .gitignore to exclude large files"
git push XXX main:main --force

如果已经在过去的几次commit提交了，并且知道在哪个commit开始出现，可以使用以下方法

# 1. 撤销最近的提交，但保留更改
git reset --soft HEAD~1
# 如果大文件在更早的提交（比如倒数第二次），用 HEAD~2 或具体哈希：
# git reset --soft abc123^ # abc123 是包含大文件的提交

# 2. 移除大文件
git rm --cached "大文件名"

# 3.重新提交
git commit -m "Remove large file XXX"

# 4. 强制推送
git push XXX main:main --force

我写了一个git hooks 文件，在commit大于设定size的文件的时候，拦截commit，并且把大文件名写入.gitignore ，同时从缓存区中移除大文件进行版本控制的时候，经常会由于大文件导致上传github出问题，并且版本回退也比较麻烦。实际上我们很少代码文件会超过50M，而往往是由于数据文件过大导致错误，这些数据文件往往我们可能都不需要进行版本控制于是，不如直接通过脚本，默认不对这些大文件进行版本控制

代码（文件名设置为pre-commit，防在.git/hooks目录下，注意文件名要一致，这涉及到git hooks的逻辑，不做过多解释）


#!/usr/bin/env python3
# 我在2025年之前用的是 #!/bin/python,但是报错了，改成了上面的内容
import subprocess
import os


if __name__ == "__main__":
 files = subprocess.check_output(['git', 'diff', '--cached', '--name-status'], text=True, encoding='utf-8').split('\n')
 for file in files:
 if len(file.split("\t")[0]) > 0 and file.split("\t")[0] != 'D':
 file_path = file.split("\t")[-1]
 file_size = os.path.getsize(file_path)
 size_in_mb = file_size / (1024 * 1024)
 if size_in_mb >= 50:
 with open('.gitignore', 'a', encoding='utf-8') as f:
 f.write(file_path + '\n')
 try:
 # Remove the file from the Git index (staged area)
 subprocess.check_output(['git', 'rm', '--cached', file_path])
 print("Removed {} from stage".format(file_path))
 except subprocess.CalledProcessError as e:
 print("Error removing file from stage: {}".format(e))

 try:
 # Reset the file to unstage changes
 subprocess.check_output(['git', 'reset', file_path])
 except subprocess.CalledProcessError as e:
 print("Error while resetting file: {}".format(e))

 print("The file is larger than 50MB and has been added to .gitignore. Please confirm and recommit!")
 print(file_path + "\n")
 exit(1)

下面可以配置全局Git 钩子

LINUX平台

# 创建全局 Git 钩子目录
mkdir -p ~/.git-template/hooks

# 创建并编辑 pre-commit 钩子脚本
cat > ~/.git-template/hooks/pre-commit << 'EOF'
#!/bin/bash
MAX_SIZE=$((50 * 1024 * 1024)) # 50MB in bytes

# 获取暂存区所有文件的列表
files=$(git diff --cached --name-only --diff-filter=ACM)

for file in $files; do
 # 检查文件是否存在
 if [ -f "$file" ]; then
 # 获取文件大小（字节）
 size=$(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null)
 if [ "$size" -gt "$MAX_SIZE" ]; then
 echo "错误：文件 '$file' 超过 50MB（大小：$((size / 1024 / 1024))MB）"
 exit 1
 fi
 fi
done
exit 0
EOF

# 赋予执行权限
chmod +x ~/.git-template/hooks/pre-commit

# 配置 Git 使用全局钩子模板
git config --global init.templatedir ~/.git-template

# （可选）为现有仓库手动复制钩子（替换 /path/to/your/repo 为实际路径）
# cp ~/.git-template/hooks/pre-commit /path/to/your/repo/.git/hooks/pre-commit
# chmod +x /path/to/your/repo/.git/hooks/pre-commit

WINDOWS平台

需要 POWERSHELL 因为环境变量

# 创建全局 Git 钩子目录
$templateDir = "$env:USERPROFILE\.git-template\hooks"
New-Item -ItemType Directory -Force -Path $templateDir

# 创建 pre-commit 钩子脚本
$hookPath = "$templateDir\pre-commit"
Set-Content -Path $hookPath -Value @'
#!/bin/sh
MAX_SIZE=$((50 * 1024 * 1024)) # 50MB in bytes

# 获取暂存区所有文件的列表
files=$(git diff --cached --name-only --diff-filter=ACM)

for file in $files; do
 # 检查文件是否存在
 if [ -f "$file" ]; then
 # 获取文件大小（字节）
 size=$(wc -c < "$file")
 if [ "$size" -gt "$MAX_SIZE" ]; then
 echo "错误：文件 '$file' 超过 50MB（大小：$((size / 1024 / 1024))MB）"
 exit 1
 fi
 fi
done
exit 0
'@

# 赋予执行权限（Windows 下无需 chmod，但确保 Git Bash 支持）
# 配置 Git 使用全局钩子模板
git config --global init.templatedir "$env:USERPROFILE\.git-template" # 如果你不用变量，那么就赋绝对路径

# （可选）为现有仓库手动复制钩子（将以下路径替换为实际仓库路径）
# $repoPath = "C:\path\to\your\repo"
# Copy-Item -Path $hookPath -Destination "$repoPath\.git\hooks\pre-commit"

也可以按照下面进行手动配置

首先创建一个文件夹，然后git init，可以手动将上面代码粘贴修改pre-commit文件

配置全局钩子，需要绝对路径

可以测试一下，原理就是git init的时候，把设置的这些配置复制一份

cannot_lock_ref_error

root@ce4322c051c6:/codes/dataAnalysisModels# git pull
remote: Enumerating objects: 193, done.
remote: Counting objects: 100% (193/193), done.
remote: Compressing objects: 100% (178/178), done.
remote: Total 191 (delta 10), reused 188 (delta 10), pack-reused 0 (from 0)
Receiving objects: 100% (191/191), 115.48 MiB | 149.00 KiB/s, done.
Resolving deltas: 100% (10/10), completed with 2 local objects.
error: cannot lock ref 'refs/remotes/zata/main': is at 801efa1db3242f2be077de0d34e4eb29af0a5751 but expected aab6c46b69629454c3ad76e5a030157169eabb6e
From github.com:zata-zhangtao/dataAnalysisAndModeling_In-GY
 ! aab6c46..801efa1 main -> zata/main (unable to update local ref)

我的解决方法是

git fetch --prune
git pull

云服务器无法访问Github导致git失败方案

可以先去这个网站，哪些ip可用

https://ping.chinaz.com/github.com

然后要修改服务器端的HOSTS

例如：

20.205.243.166 github.com
20.205.243.166 raw.githubusercontent.com

hosts位置在 /etc/hosts

知识点

GitHub Actions 密钥管理全指南：Repository、Environment 与 Organization Secrets 的区别与最佳实践

在配置 GitHub Actions CI/CD 流水线时，管理敏感信息（API Key、数据库密码、部署 Token）是重中之重。GitHub 提供了多种存储 Secrets（密钥）的方式，最常见的是 Repository Secrets，但你可能也注意到了 Environment Secrets 和 Organization Secrets。

它们到底有什么区别？如果我想让一个变量在几十个仓库里通用，又该怎么办？这篇文章将为你彻底理清这三者的关系、优先级和最佳应用场景。

一、Repository Secrets vs. Environment Secrets

这是最基础的两个概念，决定了你的密钥是在“仓库级别”可见，还是在“特定部署环境”下可见。

1. Repository Secrets (仓库级密钥)

这是最常用的类型。

位置：Settings -> Secrets and variables -> Actions -> Repository secrets
作用域：整个代码仓库。仓库内的任何 Workflow、任何分支、任何 Job 都可以直接读取。
适用场景：
- 通用的 CI 工具 Token（如 Codecov, SonarQube）。
- 构建阶段需要的非敏感于环境的凭证（如拉取私有 Docker 镜像的 Token）。

2. Environment Secrets (环境级密钥)

这是为 CD（持续部署）设计的更高级功能。

位置：Settings -> Environments -> 选择环境（如 production） -> Environment secrets
作用域：仅限在 Workflow YAML 中明确指定了该环境的 Job。
核心优势：
1. 部署保护（Deployment Protection Rules）：你可以设置 Required reviewers (人工审批)。例如，Workflow 运行到部署生产环境的步骤时会暂停，直到管理员点击"Approve”，代码才能拿到 Environment Secret 并继续执行。
2. 同名变量覆盖：允许开发环境和生产环境使用同一个变量名（如 DB_HOST），但值不同。

代码示例：如何使用 Environment Secret

jobs:
 deploy-prod:
 runs-on: ubuntu-latest
 # 关键点：必须声明 environment，才能读取到该环境下的 Secret
 environment: production 
 steps:
 - name: Deploy
 env:
 # 如果 production 环境里定义了 API_KEY，这里读到的就是生产环境的 Key
 API_KEY: ${{ secrets.API_KEY }}
 run: ./deploy.sh

3. 对比总结

特性	Repository Secrets	Environment Secrets
可见性	所有 Job 可见	仅声明 `environment: xxx` 的 Job 可见
审批机制	不支持	支持人工审批、等待计时器等
优先级	较低	最高 (覆盖同名 Repository Secret)
典型用途	单元测试、Lint 检查、构建镜像	生产环境数据库密码、AWS 生产证书

二、进阶痛点：我想定义所有仓库都能用的变量怎么办？

当你拥有 20 个微服务仓库，且都需要使用同一个 NPM Token 或者 Slack 通知 Webhook URL 时，在每个仓库里重复配置 Repository Secrets 会让人崩溃。

这时你需要 Organization Secrets (组织级密钥)。

1. 什么是 Organization Secrets？

位置：组织主页 -> Settings -> Secrets and variables -> Actions。
前提：你的仓库必须属于一个 Organization（组织账号），个人账号不支持此功能。

2. 强大的访问策略 (Access Policy)

在创建组织密钥时，你可以控制它的传播范围：

All repositories：组织下所有（现有和未来新建的）仓库都能自动读取。
Private repositories only：仅私有仓库可用（防止开源项目泄露公司 Token）。
Selected repositories：手动勾选特定仓库可用（推荐，遵循最小权限原则）。

3. Organization Variables (组织级变量)

除了加密的 Secrets，GitHub 还允许在组织级定义 Variables（明文变量）。

适用于非敏感配置，如 API_BASE_URL、COMPANY_NAME。
在代码中通过 ${{ vars.MY_VAR }} 访问。

三、终极问题：同名变量的优先级（覆盖逻辑）

如果我在 Organization、Repository 和 Environment 里都定义了同一个名字的变量（比如 DATABASE_URL），GitHub 会读取哪一个？

遵循 “越具体，优先级越高” 的原则：

Environment Secrets (最高优先级) 👑
Repository Secrets (中等优先级)
Organization Secrets (最低优先级)

实战场景：

你在 组织级 设置了 SLACK_WEBHOOK 用于日常通知。
突然有个特定仓库 Project-X 需要发送通知到另一个独立的 Slack 频道。
你只需在 Project-X 的 Repository secrets 里新建一个同名的 SLACK_WEBHOOK。
GitHub 会自动优先使用仓库级的配置，而不会影响组织内其他 99 个仓库。

四、最佳实践决策清单

在创建变量前，请对照此清单选择存储位置：

这个变量是所有（或多个）项目通用的吗？
- 是 -> Organization Secrets (如：公司通用的 NPM Token, Slack Webhook)。
- 否 -> 往下看。
这个变量涉及“生产环境”或“高风险”操作吗？
- 是（如 AWS Prod Key, 生产库密码）-> Environment Secrets (并开启人工审批保护)。
- 否 -> 往下看。
这个变量需要在不同的环境（Dev/Test/Prod）有不同的值吗？
- 是 -> Environment Secrets (在不同环境里设同名变量)。
- 否 -> 往下看。
默认选项：
- 上述情况都不是 -> Repository Secrets。

结语

掌握这三个层级的 Secrets 管理，不仅能让你的 GitHub Actions Workflow 代码更简洁（由 if/else 地狱转变为统一变量名），还能大幅提升 CI/CD 流程的安全性。

Tip: 如果你是个人开发者账号，无法使用 Organization Secrets，建议创建一个免费的 Organization 并将仓库 Transfer 进去，以便享受全局变量管理的便利。

将Python包发布到GitHub并通过pip安装的教程

创建Python包结构
构建以下目录结构：

your_package/
├── your_package/
│ ├── __init__.py
│ └── your_module.py
├── setup.py
├── README.md
├── LICENSE
└── requirements.txt

编写关键文件

setup.py 示例：

from setuptools import setup, find_packages

setup(
 name='your_package_name',
 version='0.1.0',
 packages=find_packages(),
 install_requires=[
 'requests>=2.25.1',
 ],
 author='Your Name',
 author_email='your.email@example.com',
 description='A short description of your package',
 long_description=open('README.md').read(),
 long_description_content_type='text/markdown',
 url='https://github.com/yourusername/your_package',
 classifiers=[
 'Programming Language :: Python :: 3',
 'License :: OSI Approved :: MIT License',
 ],
)

your_package/init.py：
```
__version__ = '0.1.0'
```

初始化Git并上传到GitHub

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/your_package.git
git branch -M main
git push -u origin main

创建GitHub Release（可选，但推荐）
- 访问GitHub仓库页面，点击"Releases" -> “Create a new release”
- 输入版本号（如v0.1.0），发布

通过pip安装

直接从GitHub安装：

pip install git+https://github.com/yourusername/your_package.git

指定分支：

pip install git+https://github.com/yourusername/your_package.git@branch_name

指定版本（需要有release）：

pip install git+https://github.com/yourusername/your_package.git@v0.1.0

发布到PyPI（可选，允许标准pip安装）
- 安装工具：
```
pip install twine build
```
- 构建包：
```
python -m build
```
- 上传到PyPI：
```
twine upload dist/*
```
- 之后可使用：
```
pip install your_package_name
```

注意事项：

确保setup.py信息准确
设置清晰的GitHub仓库描述和topics
使用MIT或其他合适的许可证
编写详细的README.md，包含安装和使用说明
发布到PyPI需注册账号并配置API token

git-reset—hard-head-详解andgit-reset—soft-head-详解

git reset --hard HEAD

效果：

撤销所有未提交的更改（包括工作目录和暂存区）。 HEAD 指向的提交成为当前状态，之前的修改全部丢失（不可恢复，除非有其他备份）。

git reset --soft HEAD

功能：将当前分支的指针重置到 HEAD 指向的提交，但保留工作目录和暂存区的所有更改。效果：

撤销最近的提交（将 HEAD 指针移到当前提交），但修改的内容仍保留在工作目录或暂存区。可以重新调整或重新提交这些更改。

下面我将逐个参数解释这条命令的含义：

命令分解

git reset:
- git reset 是 Git 用来重置当前分支的 HEAD（当前分支指针）到指定状态的命令。
- 它可以影响 Git 的三个主要区域：
  - 工作目录（Working Directory）：你当前编辑的文件。
  - 暂存区（Staging Area/Index）：通过 git add 添加的文件。
  - 提交历史（Commit History）：Git 仓库中的提交记录。
--hard:
- --hard 是 git reset 的一个选项，指定重置的模式。
- 它表示完全重置，不仅会移动 HEAD 指针，还会：
  - 重置工作目录中的文件内容，使其与指定的提交状态一致。
  - 清空暂存区的内容。
  - 丢弃所有未提交的更改（包括工作目录和暂存区的修改）。
- 简单来说，--hard 会让你的工作目录、暂存区和提交历史完全恢复到指定的提交状态，不可恢复已丢弃的更改。
HEAD^:
- HEAD 是 Git 中的一个指针，指向当前分支的最新提交。
- ^ 是一个相对引用，表示"当前 HEAD 的上一个提交"（即父提交）。
- 因此，HEAD^ 表示当前分支最新提交的上一个提交。
- 如果当前分支的提交历史是 A <- B <- C（C 是 HEAD），那么 HEAD^ 指向 B。

整体含义 git reset --hard HEAD^ 的作用是：

将当前分支的 HEAD 指针移动到上一个提交（HEAD^）。
重置工作目录和暂存区，使其与 HEAD^ 指向的提交状态完全一致。
丢弃当前 HEAD 提交（最新提交）以及工作目录和暂存区的所有未提交更改。

示例场景假设你的提交历史如下：

A <- B <- C (HEAD)

githook脚本版本控制管理

在 Git 项目中，.githooks 目录中的钩子（hook）脚本默认是不会被 Git 版本控制系统自动纳入版本管理的，因为 .githooks 目录通常被视为本地配置的一部分。为了将 Git 钩子脚本保留到项目中并与团队共享，你需要采取一些额外的步骤。以下是具体的方法：

方法一：将钩子脚本纳入版本控制

将 .githooks 目录重命名或移动到项目中：
- 默认情况下，Git 钩子存储在 .git/hooks 目录中，这些文件不会被 Git 跟踪。你可以将钩子脚本移动到项目的一个自定义目录（例如 githooks 或 hooks），并纳入版本控制。
- 示例：
```
mkdir githooks
mv .git/hooks/pre-commit githooks/pre-commit
```
配置 Git 使用自定义钩子目录：
- 使用以下命令告诉 Git 使用项目中的自定义钩子目录：
```
git config core.hooksPath githooks

 cd githooks
# 查找所有文件 (f) 并赋予执行权限 
find . -type f -exec chmod +x {} \;
```
- 这会让 Git 使用 githooks 目录中的钩子脚本，而不是默认的 .git/hooks。
将钩子脚本提交到版本控制：
- 将 githooks 目录添加到 Git 版本控制：
```
git add githooks
git commit -m "Add git hooks to project"
git push
```
团队成员同步配置：
- 其他团队成员在克隆或拉取项目后，需要手动运行 git config core.hooksPath githooks 来启用自定义钩子路径。或者，你可以通过脚本自动设置。

方法二：使用脚本自动安装钩子为了让团队成员无需手动配置 core.hooksPath，你可以在项目中添加一个安装脚本，自动将钩子脚本复制到 .git/hooks 目录。

创建安装脚本：
- 在项目根目录创建一个脚本（例如 install-hooks.sh）：
```
#!/bin/bash
cp githooks/* .git/hooks/
chmod +x .git/hooks/*
echo "Git hooks installed successfully."
```
- 这个脚本会将 githooks 目录中的钩子复制到 .git/hooks 目录，并确保它们具有可执行权限。

添加到版本控制：

将 install-hooks.sh 和 githooks 目录提交到 Git：

git add githooks install-hooks.sh
git commit -m "Add git hooks and install script"
git push

运行安装脚本：
- 团队成员在克隆项目后，运行以下命令来安装钩子：
```
./install-hooks.sh
```

方法三：使用 Git 模板目录如果你希望钩子脚本在所有新项目中自动生效，可以配置 Git 的全局模板目录：

创建全局钩子模板：
- 复制默认的 Git 钩子模板到自定义目录：(如果你还没有自定义模板目录，可以通过下面的代码创建一个)
```
git init --template=/path/to/custom-template
```
- 在 /path/to/custom-template/hooks 中添加你的钩子脚本。
也可以配置全局模板路径就不用第一步了：
- 设置 Git 的全局模板路径：
```
git config --global init.templateDir /path/to/custom-template
```
- 之后，任何新初始化的 Git 仓库都会使用这个模板。
- 具体的使用和介绍可见shou 配置钩子脚本，请查看用git hooks解决github大文件报错，100M限制或50M限制|大文件|50M|git hooks|git。
注意事项：
- 这种方法适合个人开发环境，但不适合团队项目，因为模板目录是本地的，无法直接共享。

方法四：使用工具管理钩子可以使用一些工具来简化 Git 钩子的管理和共享，例如：

Husky（适用于 Node.js 项目）：
- 如果你的项目是 Node.js 项目，可以使用 Husky 来管理 Git 钩子。安装 Husky 后，它会自动管理 .git/hooks 目录，并在 package.json 中定义钩子脚本。
- 安装：
```
npm install husky --save-dev
```
- 配置（在 package.json 中）：
```
"husky": {
 "hooks": {
 "pre-commit": "echo 'Running pre-commit hook'"
 }
}
```
pre-commit（适用于 Python 项目）：
- 如果是 Python 项目，可以使用 pre-commit 框架来管理钩子。创建一个 .pre-commit-config.yaml 文件，定义钩子脚本，并提交到版本控制。
- 安装：
```
pip install pre-commit
pre-commit install
```

注意事项

权限问题：
- 确保钩子脚本具有可执行权限（chmod +x githooks/*）。
- 在 Windows 系统上，可能需要额外处理文件权限问题。
跨平台兼容性：
- 如果团队成员使用不同操作系统（例如 Windows 和 Linux），确保钩子脚本是跨平台的（例如，使用 Bash 脚本或 Python 脚本）。
文档说明：
- 在项目的 README.md 中添加说明，告诉团队成员如何启用钩子（例如运行 install-hooks.sh 或设置 core.hooksPath）。
避免覆盖本地钩子：
- 如果直接覆盖 .git/hooks，可能会覆盖团队成员的本地钩子配置。使用 core.hooksPath 或脚本复制的方式更安全。

总结最推荐的方式是将钩子脚本放入项目中的 githooks 目录，提交到版本控制，并通过脚本或 git config core.hooksPath 自动配置。结合工具如 Husky 或 pre-commit 可以进一步简化管理。根据项目类型和团队习惯选择合适的方法。

当前 HEAD 指向提交 C。
执行 git reset --hard HEAD^ 后：
- HEAD 移动到 B（HEAD^）。
- 提交 C 从当前分支的提交历史中移除（但可能仍存在于 Git 的对象数据库中，直到被垃圾回收）。
- 工作目录和暂存区的内容恢复到提交 B 的状态。
- 任何未提交的更改（工作目录或暂存区）都会被永久删除。

新的提交历史变为：

A <- B (HEAD)

注意事项

数据丢失风险：--hard 会永久删除未提交的更改和指定的提交（HEAD 到 HEAD^ 之间的提交）。在执行前，建议使用 git status 检查是否有未提交的更改，或者用 git log 确认提交历史。
备份建议：如果不确定是否需要丢弃更改，可以先用 git branch backup 创建一个备份分支，以保留当前 HEAD 的状态。
远程仓库影响：如果当前分支已经推送到远程仓库（如 GitHub），执行 git reset --hard HEAD^ 后需要用 git push --force 强制推送，这可能会影响其他协作者，需谨慎操作。

总结

git reset: 重置 HEAD 到指定状态。
--hard: 完全重置，丢弃工作目录和暂存区的更改。
HEAD^: 指向当前 HEAD 的上一个提交。

这条命令的总体效果是"撤销最近一次提交并恢复到上一个提交的状态，同时丢弃所有未提交的更改"。如果你只是想撤销提交但保留更改，可以考虑使用 git reset --soft HEAD^ 或其他命令（如 git revert）。

实战 – 使用

软件版本管理与热修复流程

这是一个非常经典的软件版本管理问题。在真实的开发场景中非常常见，通常被称为**“热修复”（Hotfix）或“补丁发布”（Patch Release）**。

为了在不影响 0.6.0 开发进度的情况下修复 0.5.0 的 bug，你需要基于 0.5.0 的代码拉取一个新分支，修复 bug 后发布 0.5.1，然后再把修复代码同步回 main 分支。

以下是标准的处理流程（假设你使用的是 Git）：

第一步：找到 0.5.0 的代码并拉取新分支

通常你在发布 0.5.0 时会打一个标签（Tag），或者你能找到发布 0.5.0 时的那个 Commit 记录。我们需要基于这个点创建一个专门用于修复和发布的分支（比如叫 hotfix-0.5.1 或 release-0.5.x）：

 # 假设你的 0.5.0 标签名为 v0.5.0
git checkout -b hotfix-0.5.1 v0.5.0

 # 如果你没有打标签，可以找到当时的 commit hash（比如 a1b2c3d）
git checkout -b hotfix-0.5.1 a1b2c3d

第二步：在新分支上修复 Bug 并修改版本号

现在你的代码状态已经完全回退到了 0.5.0 发布时的样子。在这里修复那个 bug，并将项目配置文件中的版本号从 0.5.0 修改为 0.5.1（如果你有 package.json、pom.xml 等文件的话）。提交你的代码：

git add .
git commit -m "fix: 修复了 0.5.0 版本的严重 bug"
git commit -m "chore: 升级版本号至 0.5.1"

第三步：发布 0.5.1

现在你可以基于这个 hotfix-0.5.1 分支去打包、测试并发布产品了。发布完成后，别忘了打上新标签：

git tag v0.5.1
git push origin v0.5.1
git push origin hotfix-0.5.1

到这一步，你的用户已经可以拿到没有 bug 的 0.5.1 版本了，而你的 main 分支毫无影响。

第四步：将修复代码同步回 main 分支（极其重要！）

这一步绝对不能忘！否则你以后发布 0.6.0 时，这个 bug 还会再次出现（也就是所谓的回归 bug）。你有两种常见的方式将修复同步回 main：

方式 A：合并分支（Merge）—— 适合 Git Flow 等标准工作流

git checkout main
git merge hotfix-0.5.1
 # 如果有冲突，解决冲突后提交
git push origin main

注意：这可能会把 0.5.1 的版本号更改也合并进来，你可能需要在 main 分支再次修改版本号回 0.6.0-dev。

方式 B：摘取提交（Cherry-pick）—— 很多团队更喜欢这种，因为它更干净

如果你在 hotfix-0.5.1 分支上只有一两个修复 bug 的 Commit，你可以只把修复 bug 的代码拿过来，而不拿修改版本号的代码：

 # 1. 先用 git log 看一下你修复 bug 的那个 commit 的 hash 值（比如 f8e9d0c）
 # 2. 切换回 main 分支
git checkout main
 # 3. 将修复代码“摘”过来
git cherry-pick f8e9d0c
git push origin main

总结流程图

 (0.5.0) -----------------------------------> (0.6.0) [main 分支]
 | ^
 | | (同步修复代码 Merge 或 Cherry-pick)
 +--->[修 bug] ---> (发布 0.5.1) --------------+ [hotfix 分支]

通过这种方式，既保证了 0.5.0 用户的可用性，又让 main 分支可以继续安心开发 0.6.0 的新功能。

关于 Main 分支的历史记录问题

这个问题非常关键！答案是：这取决于你用哪种方式（Merge 还是 Cherry-pick）把代码同步回 main。准确地说，你关心的“记录”分为两种：修复 Bug 的代码记录（比如提交信息：“fix: 修复了 xxx”）和 0.5.1 的发布记录（比如提交信息：“chore: 升级版本号至 0.5.1” 以及 v0.5.1 的标签 Tag）。

情况一：如果你使用的是 Cherry-pick（摘取）—— 推荐方式

如果你采用的是 cherry-pick，你只把“修复 Bug"的那个 commit 拿到了 main 分支。在 main 的历史中：

能看见： 修复 Bug 的记录（但 Git 会为它生成一个新的 Commit Hash）。
看不见： 任何关于"0.5.1"字眼的记录（包括改版本号的 commit 和 0.5.1 的 tag 都不会在 main 上出现）。

结果：main 分支的历史非常干净，看起来就像是在开发 0.6.0 的过程中顺手修了一个 bug，历史记录是一条直线向前。

Cherry-pick 后的 main 记录看起来像这样：

 * 9b8c7d6 (HEAD -> main) fix: 修复了导致崩溃的严重 bug <-- 这是 cherry-pick 过来的新 commit
 * 5a4b3c2 feat: 0.6.0 的新功能 B
 * 4z3y2x1 feat: 0.6.0 的新功能 A
 * a1b2c3d (tag: v0.5.0) release: 发布 0.5.0

情况二：如果你使用的是 Merge（合并）

如果你直接在 main 分支执行 git merge hotfix-0.5.1。在 main 的历史中：

能看见： 0.5.1 分支上的所有记录，原封不动地出现在了这里。
能看见： “chore: 升级版本号至 0.5.1” 的提交。
能看见： 一个额外的合并记录（比如 “Merge branch ‘hotfix-0.5.1’ into main”）。

结果：你的 main 分支历史里会混入 0.5.1 的发布痕迹。如果在合并时遇到了代码冲突（比如 main 的版本号已经改成了 0.6.0-dev，而 hotfix 改成了 0.5.1），你还需要手动解决冲突，保留 0.6.0-dev。

Merge 后的 main 记录看起来像这样：

 * d4e5f6g (HEAD -> main) Merge branch 'hotfix-0.5.1' into main <-- 合并节点
 |\
 | * f8e9d0c (tag: v0.5.1, hotfix-0.5.1) chore: 升级版本号至 0.5.1 <-- 0.5.1 的痕迹进来了
 | * e7d8c9b fix: 修复了导致崩溃的严重 bug
 * | 5a4b3c2 feat: 0.6.0 的新功能 B
 * | 4z3y2x1 feat: 0.6.0 的新功能 A
 |/
 * a1b2c3d (tag: v0.5.0) release: 发布 0.5.0

总结与建议

如果你不想在 main 分支里看到 0.5.1 这种历史版本号的“噪音”，只想要修复 bug 的代码，那么极其建议使用 cherry-pick。

这是大型开源项目（比如 Vue, React）和大多数商业公司的标准做法：

main 分支永远只看前方（0.6.0、0.7.0）。
旧版本（0.5.0）出了问题，在旧版本对应的分支（hotfix-0.5.x）上修补并发布 0.5.1。
把修补代码像“摘樱桃”一样（cherry-pick）摘回 main 分支。

这样 main 里就看不见 0.5.1 的版本发布记录，但 Bug 确实被修好了。

变基合并多个提交

# 例:变基合并最近2个提交
git rebase -i HEAD~2

这个命令会打开你的默认文本编辑器（通常是 Vim、VSCode 或 Nano），显示类似以下内容：

pick c2b3a4d 实现用户登录API
pick d3c4b5a 添加输入验证
pick e4d5c6b 移除调试日志
pick f5e6d7a 修复拼写错误

# 变基 b1a2b3c..f5e6d7a 到 b1a2b3c（4个提交）
#
# 命令:
# p, pick <提交> = 使用提交
# r, reword <提交> = 使用提交，但编辑提交信息
# e, edit <提交> = 使用提交，但停下来修改提交
# s, squash <提交> = 使用提交，但合并到前一个提交
# f, fixup <提交> = 类似于"squash"，但丢弃提交信息
# x, exec <命令> = 使用shell运行命令（其余行）
# b, break = 在此处停止（稍后用'git rebase --continue'继续）
# d, drop <提交> = 删除提交
# l, label <标签> = 用名称标记当前HEAD
# t, reset <标签> = 重置HEAD到标签
# m, merge [-C <提交> | -c <提交>] <标签> [# <单行信息>]
# . 创建合并提交，使用原合并提交的信息（如果没有原合并提交，则使用单行信息）

我们需要将后面的3个提交"压缩"（squash）到第一个提交中。编辑文件如下：

pick c2b3a4d 实现用户登录API
squash d3c4b5a 添加输入验证
squash e4d5c6b 移除调试日志
squash f5e6d7a 修复拼写错误

保存并关闭编辑器。Git 会开始处理这些提交，然后再次打开编辑器让你编辑合并后的提交信息。

第四步：编写合并后的提交信息

你会看到一个新的编辑器窗口，显示所有被合并提交的信息：

# 这是一个合并了4个提交的组合提交。
# 第一个提交信息：
实现用户登录API

# 这是第二个提交信息：
添加输入验证

# 这是第三个提交信息：
移除调试日志

# 这是第四个提交信息：
修复拼写错误

# 请输入新的提交信息，以说明此组合提交的更改。
# 以'#'开头的行将被忽略，空信息会中止提交。

删除所有内容，编写一个新的、更有意义的提交信息

保存并关闭编辑器，Git 就会完成变基操作。

多轮代码提交后才发现重大Bug？如何优雅地修改“上上个” Commit

这是一个为你整理好的博客笔记模板，标题和结构都优化过了，适合发布在 CSDN、掘金、Notion 或个人博客上。

📌 问题场景

我在开发中遇到了一个棘手的情况：

位置：倒数第三个 Commit (HEAD~2) 提交的代码有问题。
需求：我需要对这个 Commit 进行大规模的修改/重构。
工具：VS Code。

直接提交一个新的 Fix Commit 虽然简单，但会让 Git 历史变得脏乱。作为有追求的工程师，我希望历史记录干净整洁。本文记录了两种处理方案：“手术刀模式 (Rebase)” 和 “推土机模式 (Reset)”。

🛡️ 核心前提：建立安全沙盒

在修改 Git 历史前，永远不要直接在主分支（如 main/dev）上操作！ 一旦操作失误（如变基失败），很难恢复。

正确做法：新建一个临时分支进行"实验"。

git checkout -b fix-old-commit
# 所有的修改都在这个分支上进行，确认无误后再合并回主分支或强推。

方案一：手术刀模式 (Interactive Rebase)

适用场景：只想精准修复那个错误的 Commit，且必须保留它后面提交的 Commit 记录（例如后面的提交是别人写的，或者与当前修改无关）。

操作步骤

启动变基：在 VS Code 终端输入命令，回溯到前 3 个版本：

git rebase -i HEAD~3

标记要修改的 Commit： Git 会弹出一个编辑器（或 git-rebase-todo 文件），找到那个有问题的 Commit，将行首的 pick 修改为 edit。

pick -> edit

修改代码：保存并关闭文件后，Git 会暂停在那个 Commit 的时间点。此时在 VS Code 中进行大规模的代码修改。
提交修正：改完后，暂存文件并修补当前 Commit：

git add .
git commit --amend --no-edit

完成变基：应用后续的提交，回到现代：

git rebase --continue

(如果有冲突，在 VS Code 中解冲突 -> add -> continue 即可)

方案二：推土机模式 (Reset –soft)

适用场景：觉得最近这几次提交都很乱，或者逻辑强相关。不如把最近的 3 个 Commit 撤销掉，捏成一个完美的 Commit。

操作步骤

软重置：将指针回退 3 步，但保留文件修改在暂存区：

git reset --soft HEAD~3

状态变化：此时，过去 3 次提交的历史记录消失了，但所有的代码变动都还在，并且处于 Staged (暂存区/绿色) 状态。
修改与重构：直接在现在的代码基础上进行大规模修改、修复 Bug。
提交新版本：

git commit -m "refactor: 重构核心逻辑（合并了之前的多次尝试）"

⚖️ 方案对比总结

特性	方案一：Rebase -i (变基)	方案二：Reset –soft (重置)
形象比喻	精准手术 🔪	推土机 🚜
历史记录	保持原有提交数量，只修改其中一个	将多个历史提交合并为一个新提交
后续提交	保留后续 Commit 的独立性	后续 Commit 也会被合并掉
冲突风险	可能会遇到多次冲突（每个后续 Commit 都可能冲突）	无冲突（因为是一次性提交）
推荐指数	⭐⭐⭐⭐ (团队协作且需保留历史时)	⭐⭐⭐⭐⭐ (个人开发或整理烂代码时)

💡 VS Code 插件推荐

如果你不习惯命令行，推荐安装 Git Graph。

Rebase: 右键父节点 -> Rebase current branch on this commit -> 勾选 Interactive。
Reset: 右键目标节点 -> Reset current branch to this commit -> 选择 Soft。

最后提示：如果你修改的分支已经 Push 到了远程且有同事在协作，请务必与同事沟通，因为修改历史记录需要 git push -f (强制推送)，这可能会覆盖同事的代码！

如何彻底删除 Git 历史记录中的大文件

本教程旨在解决一个常见问题：当你在 git push 时，即使已经删除了某个大文件，GitHub 依然提示 GH001: Large files detected 错误，导致推送失败。

问题场景

你执行了 git rm a_large_file.pkl 并创建了一个新的 commit，但在推送时仍然看到类似下面的报错：

remote: error: File your_project/a_large_file.pkl is 107.01 MB; this exceeds GitHub's file size limit of 100.00 MB
remote: error: GH001: Large files detected.
! [remote rejected] main -> main (pre-receive hook declined)

原因是： Git 会保存每一次的提交记录。虽然你在最新的提交中删除了该文件，但它依然存在于仓库的过往历史中。推送时，GitHub 会检查所有历史记录，发现这个超大文件后便会拒绝接收。

要解决此问题，必须从 Git 的历史记录中将该文件彻底清除。

推荐方案：使用 git-filter-repo (更简单、更快速)

git-filter-repo 是 Git 官方现在推荐用来清理历史记录的工具，它比 Git 的原生命令更高效且易于使用。

1. 安装 git-filter-repo

如果尚未安装，请先执行安装。

macOS (使用 Homebrew):
```
brew install git-filter-repo
```
对于其他系统，请参考其官方安装文档。

2. 从历史记录中删除文件

在你的本地仓库根目录运行以下命令。此操作会重写历史记录。

# 将 "path/to/your/large_file.pkl" 替换为你的大文件实际路径
git filter-repo --path "path/to/your/large_file.pkl" --invert-paths

这条命令会自动处理所有分支和标签，从中移除对指定文件的所有引用。

3. 强制推送到远程仓库

由于本地历史已被重写，你需要强制推送来覆盖远程仓库的历史。

git push --force

备选方案：使用纯 Git 命令 git filter-branch

如果你不想安装任何新工具，可以使用 Git 内置的 filter-branch 命令。

警告： 此命令非常复杂且速度慢，操作前强烈建议备份你的整个项目文件夹。

1. 执行历史重写命令

# 将 "path/to/your/large_file.pkl" 替换为你的大文件实际路径
git filter-branch --force --index-filter \
'git rm --cached --ignore-unmatch "path/to/your/large_file.pkl"' \
--prune-empty --tag-name-filter cat -- --all

--ignore-unmatch: 确保在不包含该文件的历史 commit 上命令不会报错。
此命令执行速度可能很慢，请耐心等待。

2. 清理仓库并回收空间

filter-branch 会留下备份。运行以下命令以彻底清除旧数据并压缩仓库。

git reflog expire --expire=now --all
git gc --prune=now --aggressive

3. 强制推送

同样，你需要强制推送来更新远程仓库。

git push --force

未来建议：使用 Git LFS 管理大文件

为了从根源上避免此类问题，当项目中必须包含大文件时，应使用 Git Large File Storage (LFS)。

Git LFS 会将大文件存储在专门的服务器上，而在你的仓库中只保留一个轻量级的指针文件，从而使仓库保持小巧和快速。

LFS 快速上手

安装 LFS 客户端
```
# macOS
brew install git-lfs
```
在仓库中启用 LFS (每个项目只需执行一次)
```
git lfs install
```
追踪指定类型的文件 (例如，所有 .pkl 和 .onnx 文件)
```
git lfs track "*.pkl"
git lfs track "*.onnx"
```
提交 .gitattributes 文件 git lfs track 命令会创建一个 .gitattributes 文件，确保将它添加到版本控制中。
```
git add .gitattributes
git commit -m "Configure Git LFS to track large files"
```
之后，你就可以像平常一样 git add 和 git commit 大文件了，LFS 会自动处理它们。

如何优雅地处理不再使用的 GitHub 仓库

当一个项目长期不用，但又不想彻底删除时，你有以下三种方法可以将其"隐藏"起来，同时保留代码。

方案一：归档仓库 (Archive) - ⭐最推荐

这是 GitHub 官方设计的最佳方案，用于封存项目。

效果:

仓库从你的主页列表消失。
项目变为只读，无法再推送新代码。
完整保留所有代码、提交历史、Issues、PRs、Wiki 和 Star。
可以随时一键"取消归档"来恢复项目。

操作步骤:

进入仓库页面，点击 Settings (设置)。
在 General (常规) 标签页，拉到最下方的 Danger Zone (危险区域)。
点击 Archive this repository (归档这个仓库) 并确认。

方案二：设为私有仓库 (Make Private)

如果只是不想让公众看到，但自己还可能修改。

效果:

仓库从公开主页消失，只有你和协作者可见。
所有功能（推送、提交）完全正常。
注意： 仓库在你自己的仓库列表中依然可见。

操作步骤:

进入仓库 Settings -> General -> Danger Zone。
点击 Change repository visibility (更改仓库可见性)。
选择 Make private (设为私有) 并确认。

方案三：作为另一项目的分支 (不推荐)

将旧仓库的历史合并到另一个项目中，然后删除旧仓库。这是一种复杂且有损的操作。

效果:

代码和提交历史被合并到新项目的一个分支上。
警告： 将永久丢失旧仓库所有的 Issues、PRs、Wiki 等宝贵记录。
会使主项目的历史变得复杂。

操作步骤 (命令行):

# 1. 进入你的主项目目录
cd /path/to/main-project

# 2. 添加旧仓库为临时远程源
git remote add old_repo https://github.com/user/old-repo.git

# 3. 拉取旧仓库数据
git fetch old_repo

# 4. 基于旧仓库历史创建新分支 (假设其主分支为 main)
git switch -c archive/old-project old_repo/main

# 5. 推送新分支到主项目
git push -u origin archive/old-project

# 6. 删除临时远程源
git remote remove old_repo

# 7. 去 GitHub 网站上手动删除 old-repo 仓库

总结对比

方法	优点	缺点	推荐度
归档 (Archive)	保留所有记录、操作简单、可逆	项目只读	⭐⭐⭐⭐⭐
设为私有 (Private)	不公开、可继续编辑	仍在自己列表显示	⭐⭐⭐⭐
作为分支合并	物理上整合代码	丢失Issues/PRs等记录、操作复杂	⭐

结论： 对于"长期不用但想完整保留"的场景，请始终选择归档 (Archive)。

一个电脑想要同时使用两个github账号ssh登录

第一步，生成另一个账号专用的ssh密钥和公钥，然后把公钥复制到那个账号的github里面
配置客户端以使用正确账号

vim ~/.ssh/config

# zata-zhangtao 账号专用
Host github.com-zata
 HostName github.com
 User git
 IdentityFile ~/.ssh/id_ed25519_zata
 IdentitiesOnly yes

然后更新 remote URL ，使用自定义的Host

# 例如原本是： git@github.com:zata-zhangtao/ZataTree.git ，改成
git remote set-url zata git@github.com-zata:zata-zhangtao/ZataTree.git

恢复被 Git 合并覆盖的提交并防止未来覆盖

问题背景主分支（main）的修改在合并（如 zata_ssh/hugo）时被覆盖，可能是快速合并或 ort 策略自动选择远程分支内容导致。

恢复被覆盖的提交

查看历史：
```
git reflog main
```
找到合并前的提交（如 b510d7b）。

恢复提交：

git checkout main
git reset --hard b510d7b

备份分支：
```
git branch main-backup main
```
推送更改（谨慎）：如果已推送到远程，需强制推送：
```
git push --force
```
警告：提前通知团队，强制推送会影响远程历史。

重新合并（避免覆盖）

拉取远程分支：
```
git fetch zata_ssh
```

非快速合并：

git merge --no-ff zata_ssh/hugo

若有冲突，手动解决：

git add <file>
git commit

或使用变基：

git checkout zata_ssh/hugo
git rebase main
git checkout main
git merge zata_ssh/hugo

预防未来覆盖

禁用快速合并：

git config --global merge.ff false
git config --global pull.ff only

预览差异：
```
git diff main zata_ssh/hugo
```

测试合并：

git checkout -b temp-merge
git merge zata_ssh/hugo

注意事项

检查合并提交（61d17c8, 14e36c9）的文件变化：
```
git show 61d17c8
```
确认 main 跟踪分支：
```
git branch -vv
```

当前正在进行代码的开发，但是想要看历史commit的项目完整代码，而当前的工作区保证原样

# 临时保存当前工作目录中的未提交更改
git stash

# 切换到指定的 commit（替换 <commit id> 为实际的 commit 哈希值，例如 b2dfde96604dcce732aefccc4c7b4dc1fc8b161a）
git checkout <commit id>

# 返回到原始分支（替换 <branch name> 为实际的分支名，例如 main）
git checkout <branch name>

# 恢复之前保存的更改
git stash pop

在 Git 中，如果你想回退到上一个版本继续开发，同时保留已经提交到 `main` 分支的最新提交，可以通过创建新分支并回退的方式实现。

以下是一个推荐的方案和详细教程，基于 Git 的最佳实践，确保操作安全且保留所有历史记录。

方案一(推荐)：

基于当前代码创建一个新分支，在新分支上介绍功能修改情况
main分支回退到上一个版本
接着在main分支上进行开发

git branch <branchName> # 创建一个新分支
git log --oneline # 查看历史commit，方便下面的切换
git reset --hard <HEAD^ 或者 commitId>

方案二：

直接在main分支上使用revert方法进行回退

git revert HEAD

这会创建一个新的提交，撤销本次更改，恢复上一步状态，但保留所有提交历史。然后可以继续在 main 分支上开发。

假设你当前在`main`分支，暂存区有文件`file1.txt`和`file2.txt`，想保存到新分支`feature-branch`

git checkout -b feature-branch
git commit -m "Add file1 and file2 to feature branch"
git push origin feature-branch

排查 Git push失败问题

当 git push 失败并提示 Updates were rejected because the remote contains work that you do not have locally，可以按照以下步骤查看远程仓库中的更改并解决问题：

获取远程更改
运行 git fetch origin 下载远程仓库的最新状态，不影响本地工作目录。
比较本地与远程分支
- 查看提交历史：git log --oneline --graph --all
  显示本地 main 和远程 origin/main 的提交差异。
- 查看文件差异：git diff --name-only origin/main main
  列出远程和本地分支间更改的文件。
检查远程独有提交
使用 git log main..origin/main --oneline 查看远程 origin/main 中独有的提交。
查看具体提交内容：git show <commit-hash>。
合并远程更改
运行 git pull origin main 合并远程更改到本地。如有冲突，手动解决后提交。
然后推送：git push origin main。
谨慎使用强制推送
若确定覆盖远程更改，运行 git push origin main --force（注意：可能丢失他人工作，仅在确认安全时使用）。

建议：优先检查远程更改（git fetch 和 git log），根据需要合并（git pull）或强制推送。

推送当前分支到远程仓库并保持分支名

要将当前分支推送到远程仓库并保持当前分支的名字，可以按照以下步骤操作：

步骤

确认当前分支：确保你位于正确的分支。运行以下命令查看当前分支：
```
git branch
```
当前分支会有一个 * 标记，例如 * 0710display-prototype3。
推送当前分支到远程仓库：使用以下命令将当前分支推送到远程仓库（通常是 origin），并保持相同的分支名：
```
git push origin $(git branch --show-current)
```
- git branch --show-current 会返回当前分支的名称（例如 0710display-prototype3）。
- git push origin <branch-name> 将当前分支推送到远程仓库的同名分支。
设置上游分支（如果需要）：如果这是第一次推送当前分支到远程仓库，Git 可能会提示当前分支没有上游分支（no upstream branch）。你可以通过以下命令推送并同时设置上游分支：
```
git push --set-upstream origin $(git branch --show-current)
```
或者简写为：
```
git push -u origin $(git branch --show-current)
```
这会将当前分支推送到远程仓库，并将远程分支设置为当前分支的上游分支，方便后续直接使用 git push 或 git pull。

示例假设你的当前分支是 0710display-prototype3，你可以运行：

git push origin 0710display-prototype3

或者更通用地：

git push origin $(git branch --show-current)

如果需要设置上游分支：

git push --set-upstream origin 0710display-prototype3

注意事项

检查远程仓库：确保远程仓库（如 origin）已配置正确。运行 git remote -v 查看远程仓库的 URL。
工作区状态：确保你已提交所有更改（git commit），否则运行 git status 检查是否有未提交的更改。
分支名冲突：如果远程仓库已存在同名分支，推送可能会失败（例如，提示需要拉取或强制推送）。可以先运行 git fetch origin 检查远程分支状态，或者使用 git push --force（谨慎使用，仅当你确定要覆盖远程分支）。

验证推送推送完成后，运行以下命令确认远程分支已创建：

git fetch origin
git branch -r

你应该能看到 origin/0710display-prototype3 在远程分支列表中。

如果遇到任何错误（例如权限问题或冲突），请分享错误信息，我可以帮你进一步排查！

git pull 时出现 “cannot lock ref” 错误的解决方案

当执行 git pull 时出现类似以下错误：

error: cannot lock ref 'refs/remotes/zata/hugo': unable to resolve reference 'refs/remotes/zata/hugo': reference broken

这个错误通常是因为本地的 Git 引用缓存与远程仓库状态不一致导致的。

问题原因

远程分支被强制更新：远程仓库的分支可能被强制推送（git push --force），导致本地缓存的提交哈希值与远程最新的提交哈希值不匹配。
本地引用损坏或不一致：本地的 .git/refs/remotes/ 文件可能被锁定、损坏，或者由于网络中断等原因未正确更新。
Git 缓存问题：Git 的引用日志或跟踪分支信息可能出现了问题，导致无法正常同步。

解决方法以下是几种解决方法，建议按顺序尝试：

方法 1：清理并重新拉取

git fetch --prune
git pull

git fetch --prune 会更新本地对远程分支的跟踪信息，并删除远程已不存在的分支引用。

方法 2：强制更新本地引用 如果确认远程分支的最新状态是你需要的，可以强制更新本地的远程分支引用：

git fetch origin
git update-ref refs/remotes/zata/hugo origin/hugo
git pull

git update-ref 手动将本地的远程分支引用更新为远程分支的最新状态。

方法 3：删除并重置本地跟踪分支

rm .git/refs/remotes/zata/hugo
git fetch origin
git pull

手动删除本地引用文件，然后重新获取远程分支信息并拉取。

方法 4：检查锁文件 错误信息提到"cannot lock ref"，可能是因为存在锁文件导致引用无法更新：

rm .git/refs/remotes/zata/hugo.lock
git fetch
git pull

如果存在锁文件，删除它以解除锁定。

方法 5：彻底清理并重新克隆（最后手段） 如果以上方法都无效，且你不介意丢失本地未提交的更改：

cd ..
rm -rf ZataTree
git clone https://github.com/zata-zhangtao/ZataTree.git
cd ZataTree

注意：在执行此操作前，请备份所有本地未提交的更改（例如通过 git stash 或复制工作目录）。

预防措施

避免强制推送：如果多人协作，尽量避免对公共分支使用 git push --force，改用 git push --force-with-lease 以减少冲突。
定期清理：定期运行 git fetch --prune 清理无效的远程分支引用。
检查网络：确保网络连接稳定，避免 git pull 中断导致引用不一致。

Git 无法识别文件名大小写更改？一文彻底解决重命名难题

适用场景：你在 Windows 或 macOS 上将 readme.md 改为 Readme.md，但 git status 却毫无反应——别慌，这不是 Git 的 bug，而是文件系统的“锅”。本文教你如何正确处理 Git 中的大小写重命名。

你执行了如下操作：

mv readme.md Readme.md

然后运行：

git status

结果 Git 完全没反应，仿佛什么都没发生。即使你强制 git add Readme.md，Git 可能还会报错：“文件已存在”或“路径冲突”。

为什么？

Git 本身是支持文件名大小写的，但它会尊重底层操作系统的文件系统行为：

操作系统	文件系统	是否区分大小写
Linux	ext4, XFS 等	✅ 是
macOS	APFS / HFS+（默认）	❌ 否
Windows	NTFS	❌ 否

在 macOS 和 Windows 上，readme.md 和 Readme.md 被视为同一个文件。因此，当你重命名时，文件系统认为“文件没变”，Git 也就检测不到任何修改。

💡 这不是 Git 的缺陷，而是为了兼容性做出的设计选择。

✅ 正确解决方案：使用 git mv 分两步走

由于直接重命名会被文件系统“吞掉”，我们需要绕过文件系统的限制。最可靠的方法是：先改成一个临时名字，再改成目标名字。

步骤示例

假设你想把 login.js 改为 Login.js：

# 第一步：重命名为临时文件（名字不能和原名仅大小写不同）
git mv login.js temp_login.js

# 第二步：从临时文件重命名为目标文件
git mv temp_login.js Login.js

# 提交更改
git commit -m "Rename login.js to Login.js"

✅ 这样 Git 就会正确记录为一次 重命名操作，而不是“删除 + 新增”，保持历史连续性。

⚠️ 常见误区

❌ 直接在文件管理器中改名

在 Finder（macOS）或资源管理器（Windows）里右键重命名 → Git 无法感知。
结果：Git 认为原文件被删除，新文件未跟踪。

❌ 强行设置 core.ignorecase false

git config core.ignorecase false

虽然能让 Git “假装”区分大小写，但在不支持的系统上会导致状态混乱（比如误报文件丢失）。
不推荐，尤其在团队协作中可能引发更多问题。

🛠️ 高级技巧：批量重命名脚本（可选）

如果你有多个文件需要改名，可以写个小脚本：

#!/bin/bash
# rename_case.sh
old="myfile.txt"
new="MyFile.txt"

git mv "$old" "temp_$$.$old"
git mv "temp_$$.$old" "$new"
echo "Renamed $old → $new"

运行：

chmod +x rename_case.sh
./rename_case.sh

$$ 是进程 ID，确保临时文件名唯一。

🌐 跨平台协作建议

如果你的团队同时使用 Windows、macOS 和 Linux，请遵守以下规范：

避免仅靠大小写区分文件名 ❌ 不要同时存在 User.js 和 user.js
统一命名风格 ✅ 推荐全小写 + 下划线/短横线：user_profile.js 或 user-profile.js
重命名一律用 git mv 即使在 Linux 上，也养成好习惯

🔚 总结

问题	原因	解决方案
Git 不识别大小写重命名	文件系统不区分大小写（Win/macOS）	✅ 用 `git mv` 分两步重命名 ✅ 避免仅靠大小写区分文件

记住：Git 是忠实的记录者，但它的“眼睛”受限于操作系统。理解这一点，就能从容应对各种“诡异”行为。

📌 小贴士：下次遇到类似问题，先问自己——“我的文件系统真的支持这个操作吗？”

作者：你的名字标签：#Git #开发技巧 #跨平台开发 #版本控制 发布时间：2026年1月16日

如何将clone下来的项目推送到自己的新仓库并同步原始仓库更新

当你 clone 一个项目，你的本地仓库默认会有一个名为 origin 的远程连接，指向你克隆的那个仓库地址。现在你既想保留自己的修改，又想同步原始仓库的更新，并最终将所有代码推送到你自己的一个全新仓库。

下面是详细的步骤，分为两种情况：

方案一：简单直接，将推送目标"切换"到你的新仓库。
方案二：最佳实践，同时管理"原始仓库"和"你的仓库"两个远程地址。 (推荐)

前提：创建你自己的远程仓库

无论使用哪种方案，你都需要先在代码托管平台（如 GitHub、Gitee、GitLab）上创建一个空的新仓库。

非常重要： 创建仓库时，不要勾选"使用README文件初始化仓库"、“添加 .gitignore” 或 “选择许可证”，以避免产生不兼容的提交历史。

创建好之后，复制新仓库的 URL 地址（HTTPS 或 SSH 格式），比如 https://github.com/your-username/your-new-repo.git。

方案一：切换远程仓库地址 (简单直接)

这个方案直接把本地仓库的 origin 指向从原始仓库地址修改为你的新仓库地址。

第一步：提交你的本地更改

git status
git add .
git commit -m "这里写下你的提交信息，比如：添加了xx功能"

第二步：同步原始仓库的更新

git pull --rebase origin main # 如果你的分支不是 main，请替换为实际分支名

git pull --rebase 会先拉取原始仓库的新提交，再把你本地的提交"重新播放"在最前面，保持提交历史线性。
如果遇到冲突，解决后用 git add <文件名> 标记解决，然后 git rebase --continue。

第三步：更改远程仓库 origin 的 URL

git remote -v # 查看当前远程仓库地址
git remote set-url origin <你自己的新仓库URL>
git remote -v # 再次确认

第四步：推送到你自己的仓库

git push -u origin main # -u 建立本地分支与远程分支的追踪关系

方案二：添加新的远程仓库 (最佳实践)

这个方案保留了原始仓库的连接（通常命名为 upstream），同时添加你自己的仓库作为新的远程连接（通常还叫 origin）。这样做的好处是，未来你还可以随时方便地从原始仓库拉取更新。

第一步和第二步：同方案一

git add .
git commit -m "你的提交信息"
git pull --rebase origin main

第三步：重命名原始仓库并添加你自己的仓库

git remote rename origin upstream # 原始仓库重命名为 upstream
git remote add origin <你自己的新仓库URL> # 添加你自己的仓库为 origin
git remote -v # 检查远程仓库配置

此时你应该能看到：

origin 指向你的新仓库地址（可读写）。
upstream 指向你最初克隆的那个原始仓库地址（通常是只读的）。

第四步：推送到你自己的仓库

git push -u origin main

未来的工作流

推送自己的修改：git push origin main

同步原始项目的更新：

git fetch upstream
git rebase upstream/main

常见问题与注意事项

分支名不是 main？
- 如果你的分支名是 master 或其他，请将命令中的 main 替换为实际分支名。
遇到冲突怎么办？
- Git 会提示你解决冲突。解决后 git add <文件>，然后 git rebase --continue。
推送时遇到权限问题？
- 检查你是否有新仓库的写权限，或 SSH/Token 配置是否正确。
未来如何同步原始仓库的更新？
- 只需 git fetch upstream，然后 git rebase upstream/main。

开发工具链 on 扎塔-Zata

Blender 详解：奥斯卡和 AI Agent 为什么都选了它

一、一个应用，就是一整条管线

二、为什么免费还能做到这个水平

三、三次解锁：从能用，到好用，到工业级

四、AI 为什么说它"用起来方便”

五、AI+3D 管线里的位置

六、它不强的部分

七、我的判断

总结

Herdr 详解：给 AI Agent 用的终端运行时

一、它到底是什么，和 tmux 差在哪

二、安装与第一次启动

三、概念模型：workspace / tab / pane / agent

四、核心能力一：分离而不停止

五、核心能力二：状态可见——working / blocked / done / idle

六、用法：鼠标是默认，键盘是可选

七、自定义命令与弹出面板

八、关键一步：让状态真正准确——集成

九、重头戏：把 Herdr 当 Agent 的控制平面

9.1 三层接口，按需选

9.2 基础编排：起活、读输出、等结果

9.3 Agent 之间互相指挥

9.4 为什么 agent wait 不是"等命令跑完"

9.5 状态上报：report-agent 与 report-metadata 的区别

9.6 插件：宿主给挂载点，你自己接行为

9.6.1 先看宿主给了什么

9.6.2 装：两条路径

9.6.3 用：绑键、开窗格

9.6.4 插件进程能拿到什么

9.6.5 写：最小骨架

9.6.6 现成的：几类值得装的

9.6.7 试装实录：herdr-file-viewer

十、多机：本地和远程在同一个窗口

十一、配置速查

十二、避坑清单

十三、它适合谁

参考

CC Switch 详解：一个应用管住八个 AI 编程 CLI

一、它要解决的问题：配置面已经失控

二、CC Switch 是什么

三、切换的时候，内部到底改了什么

四、功能地图：六个模块各自做到什么程度

4.1 供应商管理

4.2 本地代理与故障转移

4.3 MCP、Prompts 与 Skills 统一管理

4.4 用量与成本追踪

4.5 会话管理与工作区

4.6 系统集成

五、安装与升级

六、边界与风险

七、我的判断

总结

为 AI 而写的 CLI 设计指南：原则、避坑与难点

一、为什么 Agent 时代 CLI 又重要了

二、设计原则：到底该怎么写

2.1 默认非交互（non-interactive by default）

2.2 stdout 只放结果，stderr 只放诊断

2.3 结构化输出 + 版本化 schema

2.4 语义化退出码，并写进文档

2.5 错误要「可迁移、可恢复」，并且脱敏

2.6 幂等：所有写操作的第一公民

2.7 区分「失败」和「结果未知」

2.8 配置解析要有确定的优先级

2.9 认证：让 Agent 能无人值守登录，但密钥不进 argv / history

2.10 本地先校验，未联网前拒绝非法输入

2.11 命令树与命名：一致性 > 聪明

三、重点与难点拆解

难点一：「结果未知」——网络失败不等于操作失败

难点二：幂等的边界是一个状态机

难点三：凭证存储的原子性与权限

难点四：超时要分层

难点五：轮询类交互的细节

难点六：分发与版本一致性（一个真金白银的坑）

难点七：测试策略——契约测试 + 真实入口 E2E

四、避坑清单（速查表）

五、一个最小骨架

六、交付前自检清单

参考

用 AI 把文章做成口播视频：三条路线、工具盘点与落地管线

五、核心能力二：状态可见——`working` / `blocked` / `done` / `idle`

9.4 为什么 `agent wait` 不是"等命令跑完"

9.5 状态上报：`report-agent` 与 `report-metadata` 的区别