应用能发出去了，另一个问题就冒出来了：官网还得跟着改。

发一个新构建，要修改中文首页、英文首页、两份下载页、两份更新日志。版本号改了，包大小可能没改；下载链接换了，搜索引擎读取的元数据还指着旧包。页面都能打开，里面的信息却对不上。

我这次做的事，就是让 SSHGuard 的官网和应用读取同一份发布数据。网站继续用简单的 HTML 和 CSS，Cloudflare 只负责补上容易漏改的版本信息。

这篇按实际项目讲清楚：Pages、R2 和 Pages Functions 分别做什么，为什么不用再加一份 JSON 清单，以及下一次发布到底还要手动做哪些事。

下文的部署域名、桶名、绑定名和项目专属路径均使用示例值，不代表实际后台配置。public、functions、_routes.json 等 Cloudflare 约定名称保留；使用时请将示例替换为自己的配置。

一、官网需要更新的，其实只有一小部分

先把内容分开看。

产品介绍、截图、安装指南和隐私说明，属于网站内容。它们并不会每次发版都变化，继续留在网站仓库里维护就好。

版本号、构建号、包大小、下载链接和更新日志，属于发布内容。应用打包时已经知道这些信息，再到官网手填一次，很容易出现偏差。

所以这次没有重新搭建网站，也没有引入后台管理系统。只让中文和英文的三个页面读取发布数据：

其他页面、截图和 CSS 继续按原来的方式发布。

二、Cloudflare 的几个名字，到底各管什么

第一次接触这些服务时，很容易把它们当成同一件事。我实际用到的是下面三个：

网站地址是：

1

https://apps.example.com/demo-app/

安装包和应用更新源在：

1

https://downloads.example.com/demo-app/

两个域名分别给用户看页面和下载文件。官网不会把 ZIP 读进函数再转发一次，下载按钮直接指向 R2 的公开地址。

Pages Functions 运行在 Cloudflare 的 Workers 运行时上，这个项目不用再单独建立一个 Worker 服务。R2 绑定让函数可以直接访问桶里的对象。Cloudflare 的绑定说明

部署网站时，Pages 从 GitHub 拉取代码并编译函数。用户每次打开网页，运行的是已经部署好的函数，不会再去 GitHub 读取代码。

三、网站还是静态页面，版本信息在返回前填进去

以下载页为例，网站仓库里仍然有一份正常的 HTML。它里面有标题、安装说明和最后一次核实的版本信息。

用户访问页面时，函数先取得这份静态响应，再读取 R2 中的 appcast，找到最新正式版本，替换指定位置，最后返回完整页面。

sequenceDiagram    participant U as 用户浏览器    participant P as Pages 与 Functions    participant R as R2    U->>P: 打开 SSHGuard 下载页    P->>P: 取得静态 HTML    P->>R: 读取 appcast，或使用有效缓存    R-->>P: 版本、包大小、下载地址    P->>P: 校验数据，替换指定内容    P-->>U: 返回完整 HTML    U->>R: 点击下载，直接获取 ZIP

这里的“替换”用的是 Cloudflare 的 HTMLRewriter。它可以按选择器找到 HTML 中的元素，修改文字、属性或正文。HTMLRewriter 文档

页面里的标记很简单，例如：

1
2

<h2 data-release-title>SSHGuard 1.0.0 (5)</h2>
<a data-release-zip href="旧版的真实下载地址">下载 macOS 版</a>

函数只找这些明确的标记，不靠“第三个链接”“第二段文字”这样的顺序去猜位置。后面调整页面布局，也不容易误改其他内容。

首页的 JSON-LD 也要一起更新。它是提供给搜索引擎的结构化信息；用户看不到，并不代表可以留着旧版本。版本、地址和大小会从同一份数据填入，避免正文和元数据各说各话。

浏览器拿到的已经是完整 HTML。这个版本同步功能不依赖浏览器 JavaScript，关闭 JavaScript 也能看到更新后的版本和下载链接。

四、为什么没有再加一个 releases.json

最开始考虑过给官网单独生成一份 releases.json。

它当然能工作：软件读取 appcast，官网读取 JSON。但两份文件都要记录版本、包大小和下载链接，多了一处生成、上传和核对的工作。对当前项目来说，收益不大。

SSHGuard 已经通过 Sparkle 检查更新，现有的 appcast.xml 本来就包含这些信息：

• 构建号和对外显示的版本号；
• 最低系统要求；
• 安装包的完整下载地址和字节数；
• 更新包签名；
• 更新说明地址。

Sparkle 的 appcast 使用具体 URL 指向安装包和说明，并不要求它们放在同一个目录。Sparkle 的发布说明

当前就共用这份清单。官网读取其中的元数据，再按说明链接取得正文。

不过，共用也有一个前提：不能随手裁剪 appcast 的历史条目。 官网用它列历史，删除条目后，官网也会少掉对应版本。

如果以后需要稳定版、测试版分别发通知，或者应用清单只保留少量可升级版本，官网却要保留完整历史，那时再拆一个专门的历史索引会更合适。现在先不增加这层维护。

五、更新说明改用双语 Markdown

之前发布脚本把中文 Markdown 转成 HTML，供软件显示更新说明。现在 Sparkle 2.10.0 已能显示基本 Markdown，而 SSHGuard 最低支持 macOS 14，满足其运行条件。Sparkle 从 2.9 开始提供这项支持，要求 macOS 12 及以上。Sparkle 文档

因此新版本的说明直接用：

1
2

notes.zh.md
notes.en.md

应用按语言读取说明，官网也读取同一份内容。官网把 Markdown 转成自己的 HTML，使用网站现有的排版。

这并不意味着英文会凭空出现。准备版本时，脚本会创建中英文两份草稿，发布前都需要补全和审校。这里只自动化文件生成和数据同步，函数运行时不会替用户机器翻译。

说明只使用基本标题、段落、列表、分隔线和行内代码。版本日志用不着完整的 Markdown 插件体系，也不应该把里面的任意 HTML 当作代码执行。

还有一个之前踩过的坑：UTF-8 文件本身正确，浏览器仍可能显示乱码。 上传 Markdown 时，把对象的响应类型设为：

1

Content-Type: text/markdown; charset=utf-8

官网通过函数读取后会自行渲染，但直接打开说明地址、以及软件读取说明时，也应该给出正确的内容类型和编码。

六、每个版本放在自己的目录里

安装包、校验文件和双语说明按版本放在一起，发布时上传这一组文件即可。下面以构建 6 为例，不代表它已经发布：

1
2
3
4
5
6
7
8

demo-app/
├── appcast.xml
└── releases/
    └── 1.0.0-6/
        ├── SSHGuard-1.0.0-6.zip
        ├── SSHGuard-1.0.0-6.zip.sha256
        ├── notes.zh.md
        └── notes.en.md

appcast.xml 的地址固定，每次发布更新它的内容。安装包和说明使用具体的版本地址，发布后不覆盖成另一份内容。

应用和官网都按清单中的完整 URL 找文件，不需要遍历桶，也不需要递归查找版本目录。

七、绑定 R2，不需要把访问密钥放进网页

在 Pages 项目中给 R2 配置一个绑定：

1
2

变量名：APP_RELEASES
桶名称：demo-app-releases

函数中就可以这样读取：

1

const object = await context.env.APP_RELEASES.get('demo-app/appcast.xml');

APP_RELEASES 是示例绑定名，demo-app-releases 是示例桶名。两者可以不同，但变量名大小写必须与代码一致。绑定修改后需要重新部署才能生效。R2 绑定步骤

这段代码在 Cloudflare 上运行，浏览器不会收到 R2 访问密钥，也不需要为了读取版本清单去配置浏览器跨域请求。

绑定给了函数访问桶的能力，不等于桶已经公开。函数读取清单和说明使用绑定；用户下载 ZIP 使用公开域名。它们是两条不同的访问路径，公开下载仍要单独验证。

配置后来放进官网仓库的 wrangler.jsonc，生产绑定真实更新桶，预览配置指向隔离测试桶。预览桶需要事先创建并填入测试数据，不能只写一个名字就认为资源已经存在。

八、只让六个页面运行函数

官网还承载其他应用，没必要让所有请求都绕一遍 SSHGuard 的版本逻辑。

中英文各三个页面由 middleware 接入共享处理函数，再通过 public/_routes.json 限定调用范围。目录结构大致是：

1
2
3
4

functions/
├── _lib/releases.js
├── demo-app/_middleware.js
└── en/demo-app/_middleware.js

路由明确包括首页、下载页、更新日志页，以及它们没有尾斜杠和带 index.html 的入口别名。其他应用、指南、隐私页面、图片和 CSS 保持静态服务。

不能因为只在某个目录里放了函数，就认为所有子资源都不会调用它。函数调用范围需要明确配置。Pages Functions 路由文档

这样后续调整版本同步逻辑，影响范围也容易检查：就这六页。

九、缓存与回退：网页能打开，不代表同步成功

如果每次打开下载页都读取 R2，每次打开日志页又读取一批说明，重复工作会越来越多。

当前采用两种缓存时间：

这是函数显式使用 Cache API 保存的数据缓存。R2 绑定的 get() 不会因为配置了一个 fetch 缓存参数就自动走相同机制。Cache API 的内容保存在各数据中心，不能保证全球同一时刻刷新。Cache API 文档

所以上传新清单后，某些地区的官网可能还短暂显示上一版。软件也在自己的检查时机读取更新源，不是清单上传成功后所有用户立即收到推送。

应用读取的公开 appcast 地址仍按更新源规则绕过 CDN 缓存；官网函数的五分钟内部缓存，是另一层缓存。两者不要混在一起看。

动态页面响应本身使用 no-store，避免生成的 HTML 又被长时间缓存。安装包使用独立的版本地址，适合采用较长缓存时间。

再说失败处理。读取不到清单、缺少英文说明、数据格式错误时，网站会保留整份静态页面，记录具体错误。不会只换新版标题，却留下旧版下载地址。

当前实现先把数据和替换后的完整 HTML 准备好，再返回响应，确保转换过程中出错时仍能使用原始页面。

判断是否真的同步成功，可以看响应头：

1
2

X-Release-Source: r2
X-Release-Build: 5

如果看到：

1

X-Release-Source: static-fallback

说明网站正在使用静态兜底。它能让下载页继续可用，但不保证显示最新版。静态兜底需要在网站维护时刷新，错误日志也要能查到原因。

十、这次真正踩到的坑：Functions 有依赖，构建命令不能继续留空

网站原来是纯静态 HTML，Pages 的构建命令可以留空。

加入 Functions 后，代码用了 fast-xml-parser 来解析 XML。本地已经安装依赖，所以本地编译和验证正常。云端第一次部署却报错：

1
2

No build command specified. Skipping build step.
Could not resolve "fast-xml-parser"

这两行放在一起，原因就很清楚了：这次云端没有执行依赖安装，编译函数时找不到解析器。

处理方式是在 Pages 的构建配置中设置：

npm ci 按锁文件安装依赖；npm run check 检查静态页面；之后 Pages 编译并发布 Functions。仅修改 README 不会自动改变控制台里原来留空的构建命令。Pages 构建配置

Node 版本也要明确。本项目锁定的本地工具要求 Node 22 及以上，可以在“变量和机密”中配置 NODE_VERSION，例如 22.16.0；如果选择已发布的 Node 24 版本，也应在云端实际验证一次。构建环境与版本设置

也不要按错误提示把 fast-xml-parser 标成 external 来绕过构建。函数运行时同样需要它，正确做法是安装并打包依赖。

另一个需要注意的地方是响应头：静态文件的 _headers 规则不会自动给 Functions 生成的响应补齐所有头。项目在函数响应中显式保留现有安全策略，并去掉转换后不再适用的长度和静态 ETag。Pages 响应头说明

十一、以后发布，网站和软件分别要做什么

可以把工作分成两条线。

网站代码发生变化时，例如调整布局、增加截图、修改函数逻辑，需要修改官网仓库，再通过 GitHub 与 Pages 部署。

普通软件发版时，网站函数已经部署，就只更新 R2 的发布数据，不需要为版本号再改六份 HTML。

flowchart TD    subgraph SITE[官网代码更新]        A[修改页面、截图或函数] --> B[提交并推送官网仓库]        B --> C[Pages 安装依赖、检查并部署]    end    subgraph RELEASE[普通软件发版]        D[准备并审校双语说明] --> E[本机测试、签名、公证和验证]        E --> F[生成 ZIP、校验文件、说明和候选清单]        F --> G[先上传本版文件到 R2]        G --> H[验证公开文件]        H --> I[最后发布 appcast]        I --> J[官网按缓存窗口读取新版]        I --> K[软件下次检查时发现新版]        J --> L[核对网页并登记正式发布]        K --> M[完成真实升级验收]    end

本机操作现在集中到一个入口。下面以示例脚本 scripts/release.sh 演示操作顺序，实际入口名称按自己的项目替换：

1
2
3
4
5
6
7
8

# 1. 准备构建号与中英文草稿
bash scripts/release.sh --build 6

# 2. 审校说明、删除草稿标记、提交后预检
bash scripts/release.sh --dry-run

# 3. 构建、签名、公证并生成发布文件
bash scripts/release.sh

之后仍然手动上传 R2。先上传本版目录中的 ZIP、校验文件和两份说明，然后运行：

1
2

# 4. 核对公开产物；此时清单可以仍然是上一版
bash scripts/release.sh --verify

文件核对通过，再上传 appcast：

1
2

# 5. 清单上线后再次核对，通过才登记正式发布
bash scripts/release.sh --verify --record

--record 会更新仓库中的 docs/published-appcast.xml，需要审查后提交。它不是“上传成功就记一笔”，而是公开文件和完整清单与本地一致时才登记。

最后还要检查官网六页，以及用旧应用完成一次下载、安装、重启。函数响应正常、公开文件可下载、应用实际升级成功，是三件不同的事。

Shell 脚本负责串起工具和执行顺序，Python 处理版本与 XML。日常只使用统一入口，不需要逐个运行内部脚本，也没有必要为了语言一致把它们重写成一种语言。

十二、已经验证的和还需要真跑的

目前本地已经验证了：

• 中英文六页使用同一版本、下载地址和包大小，首页 JSON-LD 同步；
• 基本 Markdown 渲染和危险内容处理；
• 日志每页十版，读取有数量及大小上限；
• 说明缺失、清单损坏时保留完整静态页面；
• 入口别名重定向正常，其他应用和静态资源保持原行为。

本地使用 Wrangler 与模拟 R2 验证。普通 Python 静态服务器只会展示兜底 HTML，不能用来判断 Functions 是否工作；本地模拟桶也不会自动读取生产数据。

初次云端部署还暴露了上面的依赖安装问题。生产环境是否已经正确绑定、函数是否真的返回动态数据，应以部署结果和响应头为准，不能因为页面能打开就认为全部完成。

构建 6 的目录只是本文示例。下一版双语说明在 Sparkle 中的实际展示、公开文件核对、旧版真实升级，都需要用正式产物再验一次。

做到这里，重复手填的版本信息基本移交给发布数据了。每次发布仍然需要认真写说明、验证用户拿到的包和完成升级验收；网站里那些“版本改了，链接忘了改”的工作，则不必再靠记忆。

地图有了，这一次真的跑了一遍。SSHGuard 的 1.0.0（构建 4）从代码提交一路走到了 Apple 公证通过、上传到 R2、更新清单上线。

结论先说：“能跑”的部分几乎不会卡住你，卡住的是“检查和验证”的部分。 公证被拒时命令返回成功、下载的包能被系统静默挪走、权限报错会跟着系统语言变化……这些都不是文档首页会写的事，是跑过一次才会知道的事。

这篇就按实际踩过的顺序讲。

一、这次真的跑通了什么

上一篇结尾时，SSHGuard 停在“签名完成、公证还没提交”。这次把整条链路走完了：

flowchart TD    A["Git 提交 1168e19"] --> B["构建号 4<br/>回归 + XCTest"]    B --> C["Developer ID 签名归档"]    C --> D["Apple 公证：Accepted"]    D --> E["附加票据、重新打包"]    E --> F["生成更新包、HTML 说明、清单"]    F --> G["上传 R2"]    G --> H["更新清单 appcast.xml 上线"]    style A fill:#dcfce7,stroke:#16a34a,color:#14532d    style D fill:#dcfce7,stroke:#16a34a,color:#14532d    style H fill:#dcfce7,stroke:#16a34a,color:#14532d

每一步都留了日志，提交 ID、公证状态、Apple 返回的公证日志都保存在本次发布目录里。剩下的只有两件事：用已安装的旧版完成一次真实自动升级验收，以及想好新用户从哪里下载。

下面按“这次新学到的东西”展开。

二、其实是三把钥匙

上一篇说签名私钥要妥善保管。实际跑下来，参与发布的不是一个私钥，而是三套不同的凭据，它们的保管方式、丢失后果都不一样：

三个细节值得单独说：

公证凭据不是 Xcode 登录。 Xcode 里登录 Apple ID 不会自动创建命令行可用的公证凭据。要走 xcrun notarytool store-credentials，输入的是 Apple 账户页面生成的 App 专用密码，不是 Apple ID 登录密码。写成独立入口（脚本里的 --setup-notary）是为了让这一步只配一次、且密码不经过脚本和 shell 历史。

最危险的是 Sparkle 私钥。 它存在用户机器上的每个已安装应用里（公钥嵌在 app 里）。丢了它，现有用户就再也收不到可信的自动更新——不是换个证书那么简单。导出命令是 generate_keys -x，恢复用 -f，注意都必须带 --account 指向你的钥匙串账户。

两把钥匙不要同时换。 更新链路的可信度由“代码签名 + EdDSA 签名”共同保证。如果某个版本同时换了 Apple 签名身份和更新密钥，旧客户端可能无法验证这次更新。分开做，中间至少隔一个正常发布的版本。

三、公证的两个坑

notarytool 的 --wait 很方便：提交后阻塞到出结果。但用起来有两个坑，第一个坑还藏得很深。

坑一：被拒时退出码可能仍是 0

直觉上“命令返回 0 = 成功”，但实际不是。公证返回 Invalid 时，submit --wait 的退出码仍可能是 0。

如果脚本只看退出码，后果是：公证已经被拒了，流程还继续往下走，到 stapler staple 时才报错——报的还是 stapler 的错误，看不出真正原因。

正确做法是按返回 JSON 里的 status 判定：

1
2
3
4
5
6

xcrun notarytool submit 应用.zip \
    --keychain-profile "$NOTARY_PROFILE" \
    --output-format json | jq -r '.id'
xcrun notarytool wait "$SUBMISSION_ID" \
    --keychain-profile "$NOTARY_PROFILE" \
    --output-format json | jq -r '.status'   # Accepted / Invalid / Rejected

把 submit 和 wait 拆成两步还有一个好处：提交 ID 先落盘，网络中断也不丢，之后可以续等。

坑二：Accepted 不代表“没问题”

公证日志里，即使状态是 Accepted，也可能有需要修复的警告项——比如某个二进制缺了安全时间戳。这些不会阻止这次发布，但可能成为下一次的坑。

无论成功失败，都拉一次日志存下来：

1
2
3

xcrun notarytool log "$SUBMISSION_ID" \
    --keychain-profile "$NOTARY_PROFILE" \
    日志路径/notary-log.json

被拒时日志里是具体原因；通过时日志里是值得修一修的警告。

顺带：网络中断不代表提交失败

--wait 因为网络断掉而退出，Apple 端的提交可能还在正常处理。这时不要重新提交（会白白多交一份），用已保存的提交 ID 续等：

1
2

xcrun notarytool wait "$SUBMISSION_ID" \
    --keychain-profile "$NOTARY_PROFILE"

这也是为什么要把提交 ID 第一时间写进日志文件。

四、“上传到下载渠道”其实是三次上传

上一篇画的时序图是两次上传：上传 Apple 检查、上传下载渠道交付。

接入自动更新之后，实际上是三次，而且顺序有讲究：

sequenceDiagram    participant D as 开发者    participant A as Apple 公证    participant R as R2 更新源    participant U as 已安装用户    participant N as 新用户    D->>A: 上传应用申请公证（检查）    A-->>D: Accepted，返回票据    D->>R: 上传 ZIP 和 HTML 说明（交付）    N->>R: 通过下载链接获取安装包    D->>R: 最后上传 appcast.xml（通知）    U->>R: 定期检查清单，发现新版本

为什么清单要最后传： appcast.xml 一上线，所有装了旧版的用户立刻会收到“有新版本”的推送。如果更新包还没就位，用户点进去会下载到 404。反过来，先传包再传清单，用户拿到的永远是已就位的版本。

这三次上传的验证内容也不同：

• 检查阶段：Apple 返回 status: Accepted、票据能 staple、Gatekeeper 通过
• 交付阶段：下载地址能访问、下载下来的 SHA256 和本地逐字节一致
• 通知阶段：清单里新版本的下载地址、文件长度、EdDSA 签名和本地生成的一致

五、ZIP 分发的隐藏坑：App Translocation

用户下载 ZIP，Safari 自动解压到「下载」文件夹。如果他直接双击打开 SSHGuard.app——macOS 会把这个 app 静默放到一个只读的隔离位置运行（App Translocation），他不会察觉任何异常。

但后果很严重：Sparkle 的自动更新在这种状态下完全静默失效。文档原话是：

By default Sparkle will not notify your user if an update cannot be performed, like if the app is running from a read-only mount or being impacted by app translocation.

也就是说，从「下载」直接打开的用户，会永远收不到新版本，而且他自己不知道。

三种补救方式，可以按成本选：

• 说明文档里写清楚：解压后把应用拖进「应用程序」文件夹再打开。最低成本，挡不住不看文档的用户。
• 应用自己检测：bundle 路径包含 /AppTranslocation/ 或以 /Volumes/ 开头时，启动弹一次提示。SSHGuard 现在就这么做，同时在设置 → 关于里常驻一个橙色警告。
• 改用 DMG：里面放一个指向「应用程序」的符号链接，引导用户拖过去。这是 Sparkle 官方推荐的做法，需要多一次公证（给 DMG 本身）。

另外，如果你的应用支持“登录时启动”之类的功能，被隔离的随机路径注册出去的行为可能也不符合预期——这又是一个“本机能跑”和“用户机器上能跑”的差异点。

六、“测试拒绝权限”要用用户的系统语言测

上一篇的测试清单里有“用户拒绝权限时，应用是否能正确处理”。实际做的时候才发现这句话缺了一个限定：用什么语言的操作系统测。

SSHGuard 用 osascript 调起 Terminal/iTerm 执行 SSH 命令。用户拒绝“自动化”授权后，osascript 返回错误码 -1743。一开始的代码靠匹配报错文本判断：

1
2
3

if detail.contains("not authorized") || detail.contains("apple events") {
    // 显示“请到 系统设置 → 隐私与安全性 → 自动化 中允许”
}

英文系统下没问题。但报错文案会随系统语言翻译，中文系统下变成：

1
2

英文：Not authorized to send Apple events to Terminal. (-1743)
中文：未获得授权将Apple事件发送给"终端"。 (-1743)

英文关键词在中文报错里一个都匹配不上。结果是：中文系统的用户拒绝授权后，看到的是一行原始报错，而不是引导他去“自动化”设置里打开的中文提示。

修复方式是认错误码，不认报错文本。 -1743 是 errAEEventNotPermitted，在任何语言的系统下都一样。

这个教训推广开来就是：凡是靠“系统文案”判断的逻辑，都要在目标用户实际使用的语言下各测一遍。 发布验收里现在专门有一条：Apple Events 拒绝路径至少在简体中文系统下测一次。

七、测试矩阵要补齐的不只是“能跑”

发布的是 universal 二进制（arm64 + x86_64），但测试只跑 arm64，Intel 切片从来没被执行过。最低支持版本写的是 macOS 14，验收却只在 macOS 27 上做。

这两件事补上之后，测试矩阵才算完整：

Rosetta 那一项成本最低收益最直接：装了 Rosetta 的 Apple Silicon Mac 上，arch -x86_64 就能把测试跑在 Intel 切片下，发现的是“只在 x86_64 路径上才出现”的问题。这次跑下来 201 个测试在 Rosetta 下全过，说明目前没有这类问题——但前提是去跑了。

八、发完之后：验证和留档

验证的是“用户拿到的那份”，不是“本地构建的那份”

打包完、上传完、能下载，只说明传输没坏。真正该验证的是从最终下载链接拿到的应用本身。

可以写成一个小脚本（verify_remote.sh），只做读取、不改任何东西：

1. 从公开地址下载 ZIP 和 HTML，HTTP 状态、Content-Type 正常
2. 下载后的 SHA256 和本地逐字节一致
3. 解压下载的 ZIP，对里面的 .app 跑 codesign --verify、stapler validate、spctl -a -vv
4. 线上 appcast 里本版本的地址、长度、EdDSA 签名和本地一致
5. appcast.xml 的响应头确认没有被 CDN 缓存

第 3 步是最关键的一环：本地 notarized/SSHGuard.app 能过验证，只说明本地的包没问题；从线上地址解压出来的那份，才是用户真正会拿到的版本。

还有一个容易漏的点：curl 下载不带 com.apple.quarantine 属性，真实用户的“浏览器下载→首次打开”流程在 curl 下载里根本走不到。要覆盖这一步，得用浏览器从公开地址下载一遍，再首次打开。

留档：Git 标签和 dSYM 不要只留在这台 Mac 上

每次发布建议做两件“将来会感谢现在”的事：

• 为发布的源码提交打 Git 标签，比如 v1.0.0-build4。source-commit.txt 记提交号已经够了，但标签让仓库自己就能回答“线上这个版本对应哪份源码”。
• 把 SSHGuard.xcarchive 备份到这台 Mac 以外的地方。 归档里的 dSYM 是将来把崩溃日志还原成可读调用栈的唯一依据。它现在躺在被 Git 忽略的 Build/ 目录里，这台 Mac 一出问题就什么都没了。注意别放进公开的更新桶——它是给开发者用的，不是给用户下载的。

九、把这些串成一条命令

上面的每一步单独看都不复杂，手动做却容易漏一步或做反顺序。所以实际做法是把这些全部串进一个入口脚本，让“下次发版”变成三件事：

1
2
3
4
5
6
7
8

# 1. 准备下一版：递增构建号，生成更新说明草稿
bash Scripts/release_local.sh --build 5

# 2. 检查说明、删除草稿标记、提交后先预览（不构建不联网）
bash Scripts/release_local.sh --dry-run

# 3. 正式运行
bash Scripts/release_local.sh

正式运行的顺序是：

flowchart LR    A["工作区干净检查<br/>公证凭据预检"] --> B["生成工程<br/>检查漂移"]    B --> C["签名证书、Rosetta<br/>更新密钥预检"]    C --> D["回归 + XCTest<br/>arm64 + x86_64"]    D --> E["签名归档"]    E --> F["公证并按 status 判定"]    F --> G["票据验证"]    G --> H["更新包、HTML、清单"]

设计上几个值得说的取舍：

预检放在最贵的操作之前。 证书、公证凭据、更新密钥、Rosetta 都在测试和归档之前检查，避免出现“公证做完了才发现缺更新密钥”的情况。

按失败阶段给不同的恢复指引。 没签名的失败可以直接重跑；归档后没提交公证可以删目录重跑；已提交公证的按 status 区分——被拒要修代码重提交，结果未知要用提交 ID 续等，已通过但后续失败不要重提公证。

“上传”始终手动。 脚本只负责本地全部可验证的产物，R2 上传和清单发布是人工步骤，顺序和注意事项写在脚本最后输出的提示里。

十、还没做完的

发布流程跑通了，但“交到用户手里”还有几件没收尾：

• 真实自动升级验收：构建 3 → 4 的完整检查、下载、安装、重启还没实际做过。本地编译通过 ≠ 用户能升级成功，这一步必须真跑。
• 新用户的下载入口：现在只有带版本号的 R2 链接，还没有固定的“下载最新版”地址。是做一个简短跳转链接、GitHub Releases，还是下载页，还在权衡。
• 发布节奏的稳定性：现在是手动上传 + 手动验收。跑得次数多了，哪些是每次必忘的步骤，会决定下一个要自动化的点在哪里。

第一篇解决的是“知道该做什么”，这一篇解决的是“实际做一遍会发现什么”。写代码和发产品之间，隔的大多是这种“不跑一遍不知道”的细节。

如果这篇里有一个点值得记住，那就是：所有只看“命令返回成功”就往下走的流程，都值得再查一层。 公证的退出码、下载的可达性、权限报错的语言——每一个都是“看起来对了”和“实际对了”之间的缝隙。

第一次开发 Mac 应用，最容易困惑的地方，是代码写完之后。

在 Xcode 里点“运行”，应用已经能打开了。但准备交给别人时，又出现了签名、证书、公证、归档、商店审核这些词。

其实可以先抓住一条主线：

把代码变成应用 → 测试 → 选择分发渠道 → 完成渠道要求 → 让用户安装。

下面从头梳理，并说明每条路径分别怎么走。

一、先看完整地图

flowchart TD    A["写好代码"] --> B["编译，生成 .app 应用"]    B --> C["测试功能、权限和异常情况"]    C --> D{"用户从哪里获得应用？"}    D --> E["只在自己的 Mac 上使用"]    E --> F["本地运行"]    D --> G["官网、GitHub 或直接发安装包"]    G --> H["Developer ID 签名"]    H --> I["Apple 公证"]    I --> J["附加票据、验证并打包"]    J --> K["上传下载渠道"]    K --> L["用户下载并安装"]    D --> M["TestFlight 测试"]    M --> N["上传 App Store Connect"]    N --> O["配置测试与必要的测试审核"]    O --> P["邀请用户试用并收集反馈"]    D --> Q["Mac App Store 正式发布"]    Q --> R["满足沙盒与商店要求"]    R --> S["上传构建和商店资料"]    S --> T["提交审核"]    T --> U["通过后发布"]    U --> V["用户从 App Store 安装"]

这几条路径不需要全部走一遍。你可以只给自己用，也可以只提供官网安装包，或者选择 App Store。

TestFlight 是测试渠道，通常服务于发布前的试用。

二、共同的起点：把代码变成应用

1. 写代码

源码里包含应用的功能、界面，以及图标等资源。

用户通常不会拿这些源码安装。他们需要的是编译好的应用。

2. 编译

Xcode 把源码转换成 macOS 可以运行的程序，最终形成：

1

SSHGuard.app

.app 看起来像一个文件，实际上是一个应用包，里面装着程序、资源和配置信息。

开发过程中，点击 Xcode 的“运行”，就会完成编译并启动应用，方便你边写边看效果。

3. 测试

编译成功，只说明程序可以被生成出来。

接下来要检查：

• 是否能启动，主要功能是否正常。
• 用户拒绝权限时，应用是否能正确处理。
• 保存、删除、恢复等操作是否安全。
• 退出再打开后，数据是否正常。
• 在支持的系统版本和设备上是否能运行。

这些工作不能由签名、公证或商店审核代替。

4. 准备发布构建和归档

准备交付时，通常会生成 Release 构建，再保存一份归档。

可以把归档理解为：把这次准备发布的版本完整留底。

flowchart LR    A["源代码和资源"] -->|"编译"| B["可运行的 .app"]    B -->|"归档"| C[".xcarchive<br/>保存发布构建"]    C -->|"导出"| D["用于交付的应用"]

.xcarchive 给开发者保存和导出使用，普通用户不需要用它安装。

完成这些共同步骤之后，再按渠道继续。

三、路径一：只给自己用

如果只是给自己做一个小工具，流程很短：

flowchart LR    A["写代码"] --> B["在 Xcode 编译运行"]    B --> C["测试和修复"]    C --> D["在自己的 Mac 上使用"]

你可以继续通过 Xcode 启动，也可以使用本地生成的应用。

在自己的开发机器上使用，不需要为了发布而提交 Apple 公证或商店审核。

但自己的电脑能运行，不代表发给别人就能顺利打开。另一台 Mac 会检查下载应用的来源，而且可能有不同的系统、权限和运行环境。

准备交给其他人时，就需要选择下面的分发方式。

四、路径二：官网、GitHub 或直接发安装包

用户从你的下载链接获得 ZIP 或 DMG，再将应用安装到自己的 Mac。

这是商店外直接分发。完整流程如下：

flowchart TD    A["测试通过的发布构建"] --> B["使用 Developer ID 证书签名"]    B --> C["上传 Apple 公证服务"]    C --> D{"公证结果"}    D -->|"未通过"| E["查看原因，修复后重新提交"]    E --> B    D -->|"通过"| F["获得公证票据"]    F --> G["将票据附加到应用"]    G --> H["验证签名、票据和系统接受状态"]    H --> I["生成最终 ZIP 或 DMG"]    I --> J["验证最终安装包"]    J --> K["上传官网或 GitHub"]    K --> L["用户下载、安装并打开"]

为了让商店外分发的应用在默认 Gatekeeper 安全设置下通过检查，需要使用 Developer ID 签名并完成公证。Apple 平台安全说明

第一步：签名——说明是谁发布的

签名可以理解为开发者给应用盖的一枚“可验证的印章”。

它帮助系统确认：

• 应用由哪个开发者签发。
• 签名之后，文件有没有被改动。

商店外分发的应用通常使用 Developer ID Application 证书签名。Apple 签名文档

证书背后还对应一个私钥。私钥用于执行签名，应妥善保存在本机或安全的构建环境中，不能当成普通文件发给别人。

第二步：公证——让 Apple 做自动安全检查

签名完成后，把应用提交到 Apple 公证服务。

Apple 会检查已知恶意内容，以及签名等必要条件。通过后，为这份软件签发公证票据。Apple 公证说明

这里要分清三件事：

公证不会替你验证所有功能，不会自动上架 App Store，也不会自动提供公开下载链接。

它只是这份软件的安全检查环节。

第三步：附加票据——让应用带着检查凭证

公证通过后，可以把票据附加到应用上，这一步叫 staple。

这样，用户的 Mac 在无法连接 Apple 服务时，也可以核验应用携带的公证凭证。

如果提交的是 ZIP，不能直接给 ZIP 附加票据。通常需要给里面的 .app 附加票据，再重新压缩。Apple 公证工作流

所以，最终发布包必须包含附加票据之后的应用。

第四步：验证和打包

发布前，要确认签名完整、公证票据有效，以及 Gatekeeper 接受应用。

Gatekeeper 就是 macOS 打开下载应用时进行安全检查的机制。即使应用已经公证，首次打开时仍可能出现正常的“是否确定打开”提示。Apple 支持说明

用户下载的包装通常有三种：

它们是包装和安装方式，不是三个不同的发布渠道。涉及安装器或磁盘映像时，还需要按对应格式处理签名和公证。Apple 打包文档

第五步：放到用户能下载的地方

官网、GitHub Releases、直接发文件，都可以交付同一份安装包。

它们都不会自动为你的应用增加更新功能。初期可以让用户手动下载新版本；应用内自动更新需要另外实现（本系列第二篇记录了接入 Sparkle 的实际过程）。

下面这张图说明了两次“上传”的区别：

sequenceDiagram    participant D as 开发者    participant A as Apple 公证服务    participant W as 官网或 GitHub    participant U as 用户    D->>D: 构建、测试并签名    D->>A: 上传应用，申请公证    A-->>D: 通过后提供公证票据    D->>D: 附加票据，验证并打包    D->>W: 上传最终安装包    U->>W: 下载    U->>U: 安装并打开应用

上传 Apple 是为了检查；上传下载渠道是为了交付。

五、路径三：Mac App Store

如果希望用户在 App Store 搜索、安装和更新应用，就走商店流程。

flowchart TD    A["检查功能能否符合沙盒和商店要求"] --> B["准备并测试商店版本"]    B --> C["创建 App Store Connect 应用记录"]    C --> D["准备介绍、截图、隐私信息等资料"]    D --> E["上传构建"]    E --> F["选择构建并提交审核"]    F --> G{"审核结果"}    G -->|"需要修改"| H["根据反馈调整应用或资料"]    H --> F    G -->|"通过"| I["按所选方式发布"]    I --> J["用户从 App Store 安装"]    J --> K["后续版本通过商店更新"]

先确认功能能否进入商店

Mac App Store 对应用有额外要求，其中包括 App Sandbox。

沙盒会限制应用可以访问的文件和系统资源。应用需要通过适当的授权和技术方案完成所需操作。Apple 沙盒文档

因此，需要访问用户文件、运行工具或与其他应用协作的软件，应提前验证这些功能能否符合要求。不能等全部做完后，才发现核心功能需要调整。

再准备商店页面和构建

App Store Connect 是开发者管理商店应用的后台。

你需要建立应用记录，准备介绍、截图和隐私信息，并上传适合商店分发的构建。

上传成功只是材料到了后台，还没有上架。

之后要提交审核。审核通过，再按选择的发布方式让用户获得应用。

商店版本也要遵守对应的更新规则。Apple 审核指南

商店审核和公证不是一回事

通过 Mac App Store 分发的应用，不需要再单独完成商店外的 Developer ID 公证流程，商店提交过程包含相应安全检查。Apple 公证说明

六、TestFlight：正式发布前先邀请用户试用

如果还没准备正式发布，希望先收集反馈，可以使用 TestFlight。

flowchart TD    A["准备测试构建"] --> B["上传 App Store Connect"]    B --> C["配置测试信息和测试人员"]    C --> D["外部测试按要求完成测试审核"]    D --> E["用户通过 TestFlight 安装"]    E --> F["收集反馈"]    F --> G["修改并上传新构建"]    G --> C

TestFlight 提供测试版的安装和反馈渠道。每个构建最多可测试 90 天，外部测试构建可能需要审核，因此不适合作为永久正式安装包。Apple TestFlight 说明

少量用户试用也可以直接领取公证安装包，不一定要使用 TestFlight。

七、每次更新，都要重新走哪些步骤？

发布不是只做一次。

假设第一版是 1.0，后来修复问题，准备发布 1.1：

flowchart TD    A["修改代码，准备新版本"] --> B["重新构建和测试"]    B --> C{"使用哪个渠道？"}    C --> D["直接分发"]    D --> E["重新签名、公证、打包和验证"]    E --> F["发布新安装包，通知或提供更新"]    C --> G["App Store"]    G --> H["上传新构建，提交新版本审核"]    H --> I["通过后发布更新"]    C --> J["TestFlight"]    J --> K["上传新测试构建并安排测试"]

上一版的签名和公证，不能直接代替修改后新版本的发布检查。

八、最后还要模拟一次用户安装

无论选择什么渠道，都应该测试用户真正拿到的版本。

从最终下载链接或测试渠道安装，检查首次启动、权限请求和关键功能，不能只测试 Xcode 里的开发构建。注意用浏览器或正常下载渠道获取安装包：curl 等命令行下载不会带上系统的 com.apple.quarantine 属性，用户真实的”下载 → 首次打开”安全检查流程在命令行下载里走不到。

对于会修改重要文件的软件，使用专用测试账户、独立测试数据或可回滚环境。

例如 SSH 管理工具，不应拿日常使用的密钥和配置去做破坏性恢复测试。

九、SSHGuard 当前走的是哪条路？

SSHGuard 当前选择的是商店外直接分发。

因为它需要管理真实的 ~/.ssh、使用系统 SSH 并与终端协作，先沿这条路径完成交付。以后是否上 App Store，再单独评估沙盒和商店要求。

当前进度如下：

flowchart TD    A["构建与归档：已完成"] --> B["Developer ID 签名：已完成"]    B --> C["Apple 公证：Accepted"]    C --> D["附加票据、最终打包与验证：已完成"]    D --> E["上传下载渠道：已完成"]    E --> F["真实自动升级验收：进行中"]     style A fill:#dcfce7,stroke:#16a34a,color:#14532d    style B fill:#dcfce7,stroke:#16a34a,color:#14532d    style C fill:#dcfce7,stroke:#16a34a,color:#14532d    style D fill:#dcfce7,stroke:#16a34a,color:#14532d    style E fill:#dcfce7,stroke:#16a34a,color:#14532d    style F fill:#fef3c7,stroke:#d97706,color:#78350f

下一步如果继续，就是提交 Apple 公证。通过后附加票据、生成最终安装包，再完成安装与功能验收。下载渠道可以随后选择官网或 GitHub Releases。

写好代码之后，真正要做的是把“开发者电脑上能运行的程序”，变成“用户拿到后能安装、能使用、能更新的产品”。

背景

最近折腾家里的网络，遇到了一个挺别扭的问题。

电脑访问正常，NAS 也正常。偏偏负责转发这些流量的路由器，自己连不上外面。

在线更新检查失败，终端里发起请求一直超时，Tailscale 也在反复报控制服务器连接失败。

它能帮别人把数据送出去，轮到自己就不行。

更让人怀疑人生的是：停掉 OpenClash，马上恢复；重新开启，又开始超时。

当时很自然地把目光放在了 OpenClash 上。是不是核心有问题？是不是本机代理规则写错了？是不是定制版本改坏了什么？

查到最后才发现，锅不能这么简单地扣过去。

这次真正撞到一起的，是三个东西：

运营商分配的 CGNAT 地址、OpenClash 的本机 TCP 重定向，以及 Tailscale 的来源防伪规则。

下面记录一下这次排查过程。设备名称、实际地址和配置信息均已脱敏。

一、最烦的地方：每个现象单独看，都像另一个问题

家里的结构并不复杂：

故障发生时，局域网设备访问正常，但路由器本机的多个 TCP 请求都超时。

这就很容易往几个方向想：

• 更新源是不是临时不可用？
• DNS 返回的地址是不是有问题？
• Tailscale 是不是连接不稳定？
• 代理节点是不是异常？
• 刚调整过的网络设置是不是留下了什么影响？

麻烦在于，这些猜测都有一点道理。

但有一条证据把范围压了下来：

同一个裸 IP 请求，OpenClash 开启时超时，关闭后立即成功。

目标没有变，也没有经过域名解析。

所以先把 DNS 放到一边。至于目标服务本身不可用，也解释不了这个开关对照。

不过，这时候只能说：

OpenClash 开启后，某条数据包路径出了问题。

还不能直接说核心坏了。

现在回头看，这个区别很重要。要是在这里就开始反复换核心、重装插件，很可能忙了一圈，问题还在。

二、先查规则，两个“看起来很像”的疑点被排除了

第一个疑点是进程身份。

进程列表显示 Clash 以 root 运行，而防回环规则匹配的是：

1

skgid 65534

乍一看，很像核心自己的出站连接没有被豁免，又被抓回代理里，绕成了一个圈。

但读取进程状态后，实际情况是：

1
2

UID：0
GID：65534

这里被进程列表误导了。

root 是用户身份，65534 是组身份，它们可以同时存在。防火墙按 socket 的组匹配，并不要求用户名也变成别的。

这个方向先划掉。

第二个疑点是本机 TCP 处理链。

当时看到 UDP 有打标规则，TCP 却没有，第一感觉是漏了什么。继续查才确认，当前模式下两者本来就走不同路径：

1
2

TCP → NAT REDIRECT → 本机代理端口
UDP → 打标 → 策略路由 → TUN

本机 TCP 链完整存在，目标端口也有 Clash 监听。发起测试后，重定向规则计数还增加了。

也就是说：

请求确实被接管了，端口也确实在监听，但连接就是建不起来。

查到这里，问题开始有点意思了。

三、一个很有用的对照：显式代理居然成功了

接着让路由器访问同一个裸 IP 目标，分别走两种方式：

这组结果比“停服务后恢复”更有价值。

同一个核心，能够处理显式代理请求，说明至少这条目标请求的处理和出站能力是正常的。

故障范围进一步缩小到了：

普通本机请求，被透明重定向之后，到底发生了什么？

此时继续盯着更新源或者远端服务器，意义已经不大了。因为失败发生在 TCP 建连阶段，连后面的 TLS 和 HTTP 都还没轮到。

该抓包了。

四、真正的转折：SYN 已经回到本机，却没人回应

短时抓包里出现了一批重复的 SYN。

脱敏后，数据包大致长这样：

1
2
3
4

入接口：lo
源地址：WAN_CGNAT_IP
目标：127.0.0.1:透明代理端口
TCP 标志：SYN

没有看到 SYN-ACK。

这里最关键的不是端口，而是源地址。

路由器准备访问外部目标时，先选用了 WAN 地址作为来源。随后 OpenClash 把目标改成本机代理端口，但原先的源地址仍然保留着。

于是，一个“路由器自己访问外面”的请求，变成了：

1
2
3

运营商分配的 WAN 地址
→ 本机回环接口
→ 本机代理端口

这条路径本身并不必然有问题。

但它会经过本机的入站检查。

而家里的路由器上，除了 OpenWrt 的防火墙，还有 Tailscale 安装的规则。

五、终于找到：Tailscale 把这个请求当成了可疑来源

继续读取完整规则集，发现 INPUT 会进入 Tailscale 的 ts-input 链。

里面有一条规则，意思很直接：

1
2
3

来源属于 100.64.0.0/10
并且不是从 tailscale0 接口进来
→ DROP

问题来了。

100.64.0.0/10 是 CGNAT 地址范围，运营商会使用，Tailscale 也使用。

路由器的 WAN 地址，恰好就在这个范围里面。

重定向之后，请求又是从 lo 进入的，当然不是 tailscale0。

两个条件都满足，直接丢弃。

代理端口虽然开着，但 SYN 在到达监听 socket 之前就被挡住了。

这也解释了为什么之前看 OpenWrt 的 fw4，明明有回环放行和 DNAT 放行，还是不通。

因为规则不只存在于 fw4 里。一个基础链放行之后，另一个基础链仍然可以把包丢掉。

Tailscale 官方也有专门的 CGNAT 兼容说明：这种地址重叠下，来源防伪规则可能同时挡住合法流量。

到这里，前面那些零散的现象终于能接起来了。

六、只换一个源地址，结果就变了

为了再确认一次，没有修改防火墙，而是让同一个请求临时绑定路由器的 LAN 地址。

其余条件保持一致。

结果：

这一下就很清楚了。

核心没换，目标没换，透明代理还在。仅仅改变来源地址，结果就从超时变成成功。

再回头看，之前觉得矛盾的地方，其实都说得通：

为什么电脑正常？

电脑的来源是局域网地址，不属于 100.64.0.0/10，不会命中这条规则。

为什么显式代理正常？

显式连接本机代理时，使用的是回环来源，同样不命中。

为什么关掉 OpenClash 就恢复？

请求不再被转送回本机，也就不会经过这条发生冲突的入站路径。

为什么 Tailscale 自己也连不上控制服务器？

它发起的本机 TCP 请求，也可能被透明代理接管，再被它自己的防火墙规则拦住。

这个结果多少有点绕：原本用来保护连接的规则，碰上另一套流量处理机制，最后把自己的连接也挡了。

七、最后怎么处理：把远程入口交给 NAS

找到原因之后，其实可以加一个精确例外。

只允许本机经回环接口访问透明代理端口，并让这类流量避开 Tailscale 的来源丢弃规则。

但临时加一条规则，和以后一直稳定，是两回事。

后面还得考虑：

• Tailscale 重启会不会重建规则？
• 防火墙重载后，例外还在不在？
• WAN 重拨换地址怎么办？
• 代理端口变化后，规则会不会失效？
• 开机时两个服务的启动顺序有没有影响？

能解决，不过家里已经有一台常开的 Unraid NAS，也运行着 Tailscale。

所以最后选择把远程访问家庭网段的入口迁到 NAS：

1
2
3
4

外部设备
→ Tailscale
→ NAS 子网路由
→ 家庭局域网

主路由器继续负责默认网关和 OpenClash。

操作顺序也没有直接“一关了之”：

1. NAS 通告家庭网段。
2. 在 Tailscale 后台批准路由。
3. 从外部网络验证能访问其他家庭设备。
4. 确认正常后，再停用路由器上的 Tailscale。
5. 检查路由器上的相关规则是否清理。

这里验证的重点，是能访问其他局域网设备。只打开 NAS 自己的页面，不能证明子网转发已经正常。

切换之后，使用恢复正常。

代价也很明确：NAS 要保持在线。它关机，远程回家的入口也就暂时没了。对一台原本就常开的设备来说，这个取舍可以接受。

八、这次折腾留下的几个提醒

最开始，确实觉得这像是 OpenClash 的问题。

毕竟开着就坏，关了就好，证据看起来已经很充分。

但沿着连接路径继续查，才发现它只是让数据包走到了另一条规则面前。真正发生冲突的，是源地址、重定向和来源检查组合起来后的行为。

以后再遇到类似情况，可以优先做这几件事：

• 裸 IP 与域名请求分开测。
• 显式代理与透明代理分开测。
• 看清楚失败是在 TCP、TLS，还是 HTTP 阶段。
• 检查所有相关防火墙表，而不只看系统默认那一张。
• 服务共存时，把“它们之间的交互”也列入排查范围。

还有一点：

电脑能上网，只能证明电脑那条路径正常。

路由器自己的请求从 OUTPUT 出发，客户端流量则从 PREROUTING 进入。看起来都经过同一台设备，实际走的规则可以差很多。

这次折腾完，至少下次再看到“电脑正常，路由器超时”，不会先急着换核心了。

先看包从哪里来、被送到哪里，又在哪条规则前停下。

比对着“连接超时”四个字猜来猜去，有用得多。

最近在折腾 Unraid 7.3 的 Internal Boot，也就是从传统 USB 启动迁移到内部 SSD 启动。

原本的目标很简单：

用一块企业级 SATA SSD 替代 U 盘，作为 Unraid 的内部启动盘，提高稳定性。

但实际迁移过程中，顺带暴露出了一堆隐藏问题：

1. Cache Pool 中一块 NVMe 已经出现真实介质错误；
2. Btrfs RAID1 虽然能自修复，但并不代表硬盘健康；
3. 512G 临时盘无法直接 replace 1T cache 盘；
4. Btrfs allocated chunk 和实际 used 不是一回事；
5. Internal Boot 写入成功后，BIOS 仍然无法从 SSD 启动；
6. LSI SAS2308 HBA 卡上的 SSD 无法被 BIOS 当作启动盘；
7. TPM 许可迁移后出现多个 key 文件冲突；
8. 迁移后 License 页面显示过期时间，引发对 legacy lifetime updates 的疑问。

这篇文章记录完整处理过程，供后续折腾 Unraid 7.3 Internal Boot、Btrfs cache pool 和 TPM license 的人参考。

二、原始环境

当前机器大致结构如下：

三、第一次发现问题：Btrfs scrub 报错但可修复

一开始执行 cache pool 的 Btrfs scrub：

1

btrfs scrub start -B /mnt/cache

第一次结果出现大量错误：

1
2
3
4

Error summary: read=256 verify=20 csum=2937
Corrected: 3213
Uncorrectable: 0
Unverified: 0

第二次 scrub 又变成：

1

Error summary: no errors found

表面看似没问题，因为：

• Corrected 不为 0；
• Uncorrectable = 0；
• 第二次 scrub 已经无错误。

但这其实只是说明：

Btrfs RAID1 成功从另一块健康盘读取正确副本，并修复了错误数据。

这不代表故障盘健康。

四、真正的硬盘故障证据：device stats 和 dmesg

继续查看 Btrfs device stats：

1

btrfs device stats /mnt/cache

结果非常明显：

1
2
3
4
5
6
7
8
9
10
11

[/dev/nvme1n1p1].write_io_errs    29513266
[/dev/nvme1n1p1].read_io_errs     88468
[/dev/nvme1n1p1].flush_io_errs    1244217
[/dev/nvme1n1p1].corruption_errs  38172
[/dev/nvme1n1p1].generation_errs  5

[/dev/nvme0n1p1].write_io_errs    0
[/dev/nvme0n1p1].read_io_errs     0
[/dev/nvme0n1p1].flush_io_errs    0
[/dev/nvme0n1p1].corruption_errs  0
[/dev/nvme0n1p1].generation_errs  0

可以确认：

/dev/nvme1n1p1 是故障盘，/dev/nvme0n1p1 是健康盘。

再看 dmesg：

1

dmesg | grep -i nvme

其中出现了关键错误：

1
2

critical medium error, dev nvme1n1
I/O Error (sct 0x2 / sc 0x81)

这类错误已经不是 APST、省电、驱动、PCIe reset 之类的问题，而是典型的：

SSD 介质 / 数据完整性错误。

即使 Windows 下 SMART 显示“健康”，只要出现：

1

Media and Data Integrity Errors > 0

就不能再把它当作可靠盘使用。

这块故障 NVMe 后续拆下来重新查看，SMART 中也能看到：

1

Media and Data Integrity Errors = 36

这个值正常应该是 0。

五、关于 SMART 的一个误区

这次有一个很典型的误区：

Windows 工具显示“健康”不代表盘真的适合继续做 NAS cache。

很多 SMART 工具主要看：

1

Critical Warning

只要它是 0，就显示“健康”。

但对 NAS / Btrfs / ZFS 来说，更重要的是：

这次坏盘的问题就是：

• Windows 健康状态正常；
• 但 Btrfs 已经发现大量读写、flush、corruption 错误；
• dmesg 已经出现 critical medium error；
• SMART 里 Media and Data Integrity Errors 已经不是 0。

所以结论很明确：

这块盘还能亮、还能读，不等于还能作为 cache / appdata / docker / VM 盘继续使用。

六、512G 替换 1T cache 盘为什么失败？

手边刚好有一块 512G NVMe，于是想直接替换故障的 1T 1T NVMe。

一开始查看：

1

btrfs filesystem show

看到 cache pool：

1
2
3

Total devices 2 FS bytes used 372.30GiB
devid 1 size 953.87GiB used 375.03GiB path /dev/nvme1n1p1
devid 2 size 953.87GiB used 375.03GiB path /dev/nvme0n1p1

这里有一个关键点：

FS bytes used 只有 372GiB，说明真实逻辑数据量并不大。

理论上 512G 应该够。

但在 Unraid GUI 或 Btrfs replace 时提示：

1
2

wrong pool state
replace device too small

原因在于：

Btrfs replace 看的不只是实际 used，还会受到 allocated chunk 的影响。

也就是说，Btrfs 可能只用了 372G 数据，但已经分配了更大的 chunk。此前 usage 中曾看到：

1

Device allocated: 741.06GiB

所以直接用 512G 替换会失败。

七、解决办法：先降级为单盘，再清理 RAID1 allocation

拆掉故障盘后，Btrfs pool 进入 degraded 状态：

1

btrfs filesystem show

显示：

1
2
3
4
5
6

warning, device 1 is missing

Label: none uuid: 1d44c14b...
Total devices 2 FS bytes used 372.28GiB
devid 2 size 953.87GiB used 375.03GiB path /dev/nvme0n1p1
*** Some devices missing

此时需要先手动 degraded mount：

1
2

mkdir -p /mnt/recovery
mount -o degraded /dev/nvme0n1p1 /mnt/recovery

确认数据还能看到后，开始 balance，把 RAID1 profile 转成 single：

1

btrfs balance start -dconvert=single -mconvert=dup /mnt/cache

最终状态变成：

1
2
3
4
5
6
7
8
9
10
11

pool status: ONLINE
Device size: 953.87GiB
Device allocated: 379.06GiB
Used: 373.54GiB
Data ratio: 1.00
Metadata ratio: 2.00
Multiple profiles: no

Data single
Metadata DUP
System DUP

这说明：

• cache pool 已经从 RAID1 降级为单盘；
• 不再 missing device；
• allocated 已经降到 379G；
• 未来再加 512G 重新转 RAID1 就可行了。

当前状态下，其实已经安全很多：

八、为什么没有立刻把 512G 加回 RAID1？

虽然现在可以加回 512G，但我最后没有急着操作。

原因是：

1. 当前 cache 已经稳定为单盘；
2. 512G 是国产消费级 NVMe；
3. 刚经历一次故障和大量 balance，不宜立刻继续重 IO；
4. 后续计划等 SSD 价格回落后，换 1T 企业 SATA / 企业 NVMe 更合适。

如果后面要重新加回 512G RAID1，可以在 GUI 中把 512G 加入 pool，然后执行：

1

btrfs balance start -dconvert=raid1 -mconvert=raid1 /mnt/cache

但当前更稳妥的是：

先单盘稳定运行，建立 appdata 备份，再决定是否恢复 RAID1。

九、240G S4610 做 Internal Boot 是否合适？

这次准备作为 Internal Boot 的盘是：

1
2

<ENTERPRISE-SATA-SSD-MODEL-REDACTED>
240G 企业级 SATA SSD

SMART 状态如下：

1
2
3
4
5
6
7
8
9

Reallocated sector count = 0
Current pending sector = 0
Offline uncorrectable = 0
CRC error count = 0
Program fail count total = 0
Erase fail count total = 0
Percent life remaining = 100%
Power on hours = 41479
Temperature = 27℃

虽然通电时间已经 4.7 年，但对企业 SATA SSD 来说不算夸张。

而且它的关键指标很干净：

• 无重映射；
• 无 pending；
• 无 uncorrectable；
• 无 CRC；
• PLP 相关项正常；
• 剩余寿命 100%。

这类企业 SATA 盘做 Unraid Internal Boot 非常合适，因为 Unraid boot 盘主要存：

• config；
• license；
• plugins；
• docker templates；
• 系统启动文件。

并不承载高频 appdata / database / VM 写入。

所以 240G 甚至是非常富裕的容量。

十、Internal Boot 页面中“专用启动池”和“启动 + 数据池”的区别

Unraid 7.3 Internal Boot 创建时，会让你选择池模式：

1. 专用启动池；
2. 启动 + 数据池。

二者区别如下：

我的选择是：

专用启动池。

原因很简单：

• Boot 和 cache 应该隔离；
• 启动盘不应承载 Docker / appdata / VM；
• 一旦启动盘坏，不应影响普通数据池；
• 这种结构更接近传统 USB boot + 独立 cache 的稳定模型。

最终设计：

十一、Internal Boot 写入成功，但拔 U 盘无法启动

Internal Boot 创建成功后，lsblk -f 显示：

1
2
3
4
5

sdc
├─sdc1
├─sdc2 vfat FAT32 EFI
├─sdc3 zfs_member flash
└─sdc4

说明：

• EFI 分区存在；
• ZFS flash boot pool 存在；
• Internal Boot 本身已经写入成功。

进一步检查 EFI 文件：

1
2
3

mkdir -p /mnt/bootssd
mount /dev/sdc2 /mnt/bootssd
find /mnt/bootssd

输出：

1
2
3
4

/mnt/bootssd
/mnt/bootssd/EFI
/mnt/bootssd/EFI/BOOT
/mnt/bootssd/EFI/BOOT/BOOTX64.EFI

这说明 EFI fallback 文件也存在。

然后通过 efibootmgr 手动创建 EFI 启动项：

1
2

efibootmgr -c -d /dev/sdc -p 2 -L "UnraidSSD" -l '\EFI\BOOT\BOOTX64.EFI'
efibootmgr -o 0000

最终：

1
2
3
4

BootCurrent: 0001
BootOrder: 0000
Boot0000* UnraidSSD
Boot0001* UEFI: USB-Boot-Device, Partition 1

看起来已经正确。

但拔掉 U 盘后，机器仍然直接进入 BIOS，Boot 页面看不到这个 SSD。

十二、最终确认：问题出在 LSI SAS2308 HBA 启动支持

最后发现一个关键事实：

这块 S4610 是通过 LSI SAS2308 HBA 连接到主板的。

这就解释了所有现象。

系统启动后，Linux 能看到 SSD：

1

sdc 223.6G <ENTERPRISE-SATA-SSD-MODEL-REDACTED>

但 BIOS 阶段看不到启动项。

这是典型的：

HBA 在操作系统里可识别，但 BIOS / UEFI 阶段不提供可启动路径。

LSI SAS2308 这类 HBA 分几个部分：

很多二手 HBA 卡只刷了 IT firmware，没有刷 UEFI boot ROM，或者主板 BIOS 不支持从这张卡启动。

所以现象就是：

最终结论：

Internal Boot 本身没有问题，问题在于启动 SSD 挂在 HBA 后，主板 BIOS 无法从该 HBA 上的 SATA SSD 启动。

解决方案有两个：

方案 A：启动 SSD 接板载 SATA

这是最推荐方案。

这是最稳、最少玄学的方案。

方案 B：给 SAS2308 HBA 补刷 UEFI ROM

理论可行，但不推荐作为首选。

原因：

• 有刷错风险；
• 不同 OEM 卡兼容性不同；
• 主板 BIOS 仍可能不认；
• HBA 初始化会拖慢启动；
• 启动盘挂 HBA 本身就不如接板载 SATA 稳。

十三、BIOS 设置踩坑

过程中也排查过华硕 BIOS 设置。

关键设置如下：

其中：

• Secure Boot 不关，Unraid EFI 可能无法启动；
• CSM 开启时，有些华硕 BIOS 不扫描 Linux EFI；
• Fast Boot 可能跳过部分存储扫描；
• 但这些都调整后仍不行，最终才确认是 HBA 启动支持问题。

十四、TPM 许可迁移后的多个 key 文件问题

Internal Boot 成功后，Unraid 进入注册页面，提示：

1
2

存在多个许可证密钥
License key type: Invalid

检查：

1

ls /boot/config/*.key

发现：

1
2

/boot/config/Basic.key
/boot/config/Plus.key

也就是 /boot/config 下有多个 key 文件。

Unraid 7.3 TPM licensing 对 key 文件更严格，只能保留一个有效 key。

最终删除旧的 Basic.key：

1
2
3

rm /boot/config/Basic.key
sync
reboot

然后重新更新密钥，许可恢复。

十五、License Expires After 是什么？

迁移 TPM license 后，页面显示：

1
2
3

Unraid Plus License
GUID: <LICENSE-GUID-REDACTED>
License Expires After: 2025-09-11

这个地方容易误解。

它不是说系统到期不能用了。

Unraid 新许可体系里：

• License 本身是永久的；
• Expire 通常指更新资格；
• 到期后当前版本仍可继续使用；
• 但是否能继续享受 lifetime updates，要看账号里 Manage Purchases 的状态。

本次账号的 Manage Purchases 中显示：

1

OS Updates: Lifetime

因此这里需要向 Unraid support 确认：

TPM 迁移后，legacy Plus license 是否仍然保留 lifetime OS updates，以及页面中的 expires after 是否只是显示问题或迁移后的兼容字段。

十六、最终状态

目前处理后的状态：

十七、这次折腾的经验总结

1. Btrfs scrub 能修复，不代表硬盘健康

如果 scrub 出现 corrected，而不是 uncorrectable，只说明镜像起作用了。

真正要看：

1
2
3

btrfs device stats /mnt/cache
dmesg | grep -i nvme
smartctl -a /dev/nvmeXn1

尤其是：

1
2
3

Media and Data Integrity Errors
critical medium error
corruption_errs

这些才是判断硬盘是否可靠的关键。

2. Windows SMART 健康状态不能作为 NAS 可靠性判断

“健康 / 优秀”只适合普通用户粗略参考。

NAS / Btrfs / ZFS 环境应该更严格：

• Media Errors 必须为 0；
• corruption 必须为 0；
• pending / uncorrectable 必须为 0；
• scrub 不应反复 corrected。

3. Btrfs 的 used 和 allocated 不是一回事

这次最大坑之一是：

1

FS bytes used 372G

但 replace 512G 仍然失败。

原因是：

1

Device allocated

过高。

Btrfs replace / shrink / balance 过程中，allocated chunk 非常关键。

4. 降容量 replace 很麻烦，重建 pool 有时反而更干净

从 1T RAID1 换到 512G RAID1，理论上只要 used 足够小就行。

但实际会受：

• allocated chunk；
• metadata；
• profile；
• balance 状态；

影响。

如果数据量可控，有时备份 appdata 后重建 cache pool 反而更简单。

5. Internal Boot 最适合用“专用启动池”

不建议把 boot SSD 同时当普通 data pool 使用。

更稳结构是：

1
2
3

小企业 SATA SSD = 专用 Internal Boot
NVMe / SSD = cache
HDD = array

6. 企业 SATA SSD 做 boot 很合适

240G S4610 这种盘虽然不新，但做 Unraid Boot 非常合适：

• 稳定；
• 有 SMART；
• 有 PLP；
• 发热低；
• 写入压力小；
• 比 USB 盘可靠得多。

7. HBA 上能被 Linux 识别，不代表能被 BIOS 启动

这是这次 Internal Boot 最大的坑。

LSI SAS2308 这类 HBA：

• 进系统后识别磁盘没问题；
• 但 BIOS 阶段不一定能从它启动；
• 取决于是否有 UEFI ROM、主板 BIOS 是否支持。

如果启动盘接在 HBA 上，遇到 BIOS 看不到启动项，优先怀疑 HBA boot support。

最稳方案：

启动盘接板载 SATA，HBA 只管数据盘。

8. TPM license 迁移后，注意 /boot/config 下只能留一个 key

如果出现：

1
2

存在多个许可证密钥
License key type: Invalid

检查：

1

ls /boot/config/*.key

只保留当前有效的 key，删除旧 key。

9. Legacy Plus 用户迁移 TPM 后，要确认 lifetime updates 状态

如果页面显示：

1

License Expires After

但账号里显示：

1

OS Updates: Lifetime

建议联系 Unraid support 确认。

尤其是 legacy Basic / Plus / Pro 用户，理论上应保留 lifetime updates。

十八、最终推荐架构

基于这次踩坑，比较稳的 Unraid 7.3 架构是：

当前更合理的最终结构应该是：

1
2
3
4
5

S4610 240G       → 板载 SATA，Internal Boot
1T NVMe  → Cache
512G NVMe        → 临时备用 / 后续 mirror
HDD Array        → 主数据
LSI SAS2308      → 只接 HDD 数据盘

十九、结语

这次迁移本来只是想把 Unraid 从 U 盘启动改成内部 SSD 启动，但实际过程中暴露出的问题远比预期多。

最终最大的收获是：

存储系统里，“能识别”和“可靠运行”是两回事；
“SMART 健康”和“适合 NAS 长期使用”也是两回事；
“EFI 文件存在”和“BIOS 能启动”仍然是两回事。

Unraid 7.3 的 Internal Boot 是一个很好的方向，但如果启动盘挂在 HBA / 扩展卡上，仍然可能踩 BIOS 启动支持的坑。

最稳的做法仍然是：

启动盘接板载控制器，数据盘交给 HBA，cache 做好备份和定期 scrub。

这次虽然过程很折腾，但也顺手发现并处理了一块已经开始出问题的 NVMe。某种意义上，Btrfs RAID1 和 scrub 算是提前救了一次数据。

一、前言

最近打开 PyCharm，你可能会看到这样一个提示：

1
2
3
4
5

Enable and try workspace mode Beta

A large project can be split into smaller parts
(like backend, API, and shared code),
making it easier to organize and maintain.

很多人第一反应：

“这是啥？”

“和普通 Project 有什么区别？”

“是不是类似 pnpm workspace？”

“Python 终于开始搞 monorepo 了吗？”

实际上：

这个功能背后，代表的是 Python 工程组织方式的一次重大升级。

而它真正对应的生态，其实是：

1

uv + pyproject.toml + workspace

这篇文章会从：

• 为什么需要 Workspace
• 什么是 Monorepo
• uv Workspace 怎么用
• PyCharm Workspace Mode 如何配合
• 实际部署怎么做
• 如何避免架构混乱

完整讲清楚。

二、传统 Python 项目的问题

很多 Python 项目最开始都长这样：

1
2
3
4
5
6
7
8

backend/
├── api/
├── utils/
├── services/
├── rag/
├── crawler/
├── scripts/
└── requirements.txt

刚开始没问题。

但项目越来越大后：

• import 开始混乱
• 共用代码越来越多
• utils 到处复制
• requirements.txt 爆炸
• IDE indexing 越来越慢
• 多服务越来越难管理

最后你会看到：

1
2
3
4

utils_final.py
utils_v2.py
shared_new/
common_latest/

整个工程开始失控。

三、为什么现在都在搞 Monorepo

现代 AI / 后端项目越来越复杂：

例如：

1
2
3
4
5
6
7
8
9

AI 平台
├── API 服务
├── Worker
├── RAG 系统
├── Agent
├── Embedding 服务
├── MCP Server
├── Shared SDK
└── 管理后台

如果每个都是独立仓库：

• 版本同步困难
• 共用代码麻烦
• SDK 更新痛苦
• 调试困难
• 本地开发复杂

于是很多公司开始统一：

1

一个大仓库（Monorepo）

四、什么是 Workspace

Workspace 本质上：

不是部署工具。

而是：

1

多项目统一开发管理

例如：

1
2
3
4
5
6
7
8
9
10
11
12
13

my-platform/
├── apps/
│   ├── api/
│   ├── worker/
│   └── crawler/
│
├── libs/
│   ├── shared/
│   ├── rag/
│   └── llm_core/
│
├── pyproject.toml
└── uv.lock

这里：

• apps 是服务
• libs 是共享代码

整个仓库：

1

一个 workspace

五、为什么 PyCharm 要推出 Workspace Mode

以前 PyCharm 的模型：

1

一个 Project = 一个工程

但现在：

一个仓库可能包含：

• API
• SDK
• Shared
• Worker
• Agent

于是 JetBrains 推出了：

1

Workspace Mode

它能自动：

• 识别多个子项目
• 建立依赖关系
• 自动配置 SDK
• 自动 linking
• 自动处理 import

六、为什么 uv 是关键

现在 Python 新生态核心正在变成：

1
2
3
4
5

uv
+
pyproject.toml
+
workspace

而不是：

1
2
3

requirements.txt
setup.py
pip

uv 是 Astral 推出的新一代 Python 包管理工具。

特点：

• 极快
• 原生 workspace
• 自动 venv
• lockfile
• monorepo 支持优秀

七、开始实战：创建 Workspace

1. 安装 uv

Mac：

1

brew install uv

Linux / Mac：

1

curl -LsSf https://astral.sh/uv/install.sh | sh

检查：

1

uv --version

2. 创建根目录

1
2

mkdir my-platform
cd my-platform

初始化：

1

uv init

3. 配置 Workspace Root

修改根目录：

pyproject.toml

1
2
3
4
5
6
7
8
9
10

[project]
name = "my-platform"
version = "0.1.0"
requires-python = ">=3.12"

[tool.uv.workspace]
members = [
    "apps/*",
    "libs/*"
]

八、创建子项目

1. 创建 API 服务

1
2
3
4

mkdir -p apps/api
cd apps/api

uv init

2. 创建共享库

1
2
3
4

mkdir -p libs/shared
cd libs/shared

uv init --lib

这里：

1

--lib

表示：

1

这是一个 library

而不是 app。

九、配置 Workspace 内部依赖

例如：

1
2
3

api
依赖
shared

那么：

apps/api/pyproject.toml

1
2
3
4
5
6
7
8
9
10

[project]
name = "api"
version = "0.1.0"

dependencies = [
    "shared"
]

[tool.uv.sources]
shared = { workspace = true }

这里：

1

workspace = true

是核心。

意思：

1
2

shared 不从 PyPI 安装
而是从当前 workspace 找

十、统一安装依赖

回到根目录：

1

cd my-platform

执行：

1

uv sync

或者：

1

uv sync --all-packages

这会：

• 创建统一 .venv
• 安装全部依赖
• 建立 workspace linking
• 生成 uv.lock

十一、PyCharm 如何配置 Workspace Mode

直接：

1

打开整个 my-platform

不是打开：

1

apps/api

然后：

PyCharm 会自动检测：

1

workspace project detected

开启：

1

Enable Workspace Mode

或者：

1
2
3

Settings
→ Project Structure
→ Use pyproject.toml-based project model (Beta)

开启即可。

十二、开启后会发生什么

PyCharm 会自动：

自动识别所有成员

例如：

1
2
3

apps/api
libs/shared
libs/rag

自动处理 import

以前：

1

from shared.utils import xxx

可能飘红。

现在：

自动识别。

自动统一 SDK

整个 workspace 共用：

1

.venv

不需要手动切换 interpreter。

十三、部署怎么办？

很多人会问：

“如果 API 依赖 shared，
那部署 API 时不是整个 monorepo 都要部署？”

答案：

1

不是

十四、要区分两种东西

1. 代码级依赖

例如：

1
2
3

shared/
rag/
llm_core/

这些本来就应该跟随 API。

因为：

API 运行需要它们。

2. 服务级依赖

例如：

1
2
3

worker/
crawler/
embedding_service/

这些不应该直接 import。

应该：

• HTTP
• gRPC
• MQ
• Redis Queue

通信。

十五、正确的 Monorepo 架构

推荐：

1
2
3
4
5
6
7
8
9
10
11
12

my-platform/
├── apps/
│   ├── api
│   ├── worker
│   ├── crawler
│   └── mcp_server
│
├── libs/
│   ├── shared
│   ├── rag
│   ├── llm_core
│   └── ai_utils

规则：

apps

独立服务。

不要互相 import。

libs

共享代码。

允许 workspace dependency。

十六、Docker 如何部署

例如：

API Dockerfile：

1
2
3
4
5
6
7
8
9

FROM python:3.12

WORKDIR /app

COPY . .

RUN uv sync --package api

CMD ["python", "-m", "api"]

这里：

1

uv sync --package api

只会安装：

• api
• api 的 workspace 依赖

不会安装整个 monorepo。

十七、推荐的一套现代 Python 技术栈

当前非常推荐：

1
2
3
4
5
6

uv
+ workspace
+ pyproject.toml
+ ruff
+ pytest
+ PyCharm Workspace Mode

这是目前 Python 新工程体系里，
最接近现代化大型工程的一种方案。

十八、总结

PyCharm Workspace Mode 的核心不是：

1

“多开几个目录”

而是：

1

Python 开始正式进入 Monorepo 时代

而 uv Workspace：

则是这个生态的真正基础。

未来几年：

1

uv + workspace

大概率会逐渐成为：

大型 Python 项目的标准组织方式。

当时第一反应是 shell 配置坏了，结果查下来不是。

现象看起来像 PATH，实际上是“断链”

先看几个关键信息：

• PATH 里有 ~/.cargo/bin
• ~/.cargo/bin/cargo 存在
• 但 cargo 是个软链：cargo -> rustup
• 真正的 ~/.cargo/bin/rustup 文件没了

也就是说，不是找不到 cargo，是 cargo 指向的目标没了。

这种情况很容易误判成“环境变量没生效”，其实是工具链启动器被清理了。

根因：self-hosted runner 和开发环境共用 HOME，被 CI 的缓存清理逻辑误伤

我项目是 GitHub Actions 跑在本机 self-hosted runner 上（同一个用户）。
Workflow 里用了 swatinem/rust-cache@v2，默认 cache-bin: true。

这件事在 GitHub-hosted runner 上通常没问题，因为机器是一次性的；
但在长期运行的 self-hosted 上，~/.cargo/bin 是你本机常驻环境的一部分，一旦 post-cleanup 动到它，就会出现这种“本机 cargo 消失”的事故。

一句话总结：CI 没删你代码，但删了你本机共享环境里的关键二进制。

最小改动修复

我最后没把缓存全关，而是只关了 bin 缓存：

1
2
3
4
5

- name: Cache Rust build
  uses: swatinem/rust-cache@v2
  with:
    workspaces: './src-tauri -> target'
    cache-bin: "false"

这行建议至少加在所有 self-hosted 的 Rust job 里（比如 macOS / Linux）。
这样还能继续缓存 registry/git/target，构建速度保住，同时避开 ~/.cargo/bin 被清理。

如果你现在已经中招了，可以先这么做

1
2
3
4

curl https://sh.rustup.rs -sSf | sh -s -- -y
source "$HOME/.cargo/env"
cargo --version
rustup show

另外建议顺手检查一下：

1
2

ls -l ~/.cargo/bin/cargo
ls -l ~/.cargo/bin/rustup

如果 cargo -> rustup 但 rustup 不存在，就是同类问题。

这类问题的通用治理建议（不只 Rust）

这次是 Rust，换成 Node/Python/Go 也可能发生。核心原则就两条：

1. 不要让 CI 和你的日常开发环境“共用生活空间”
   最好给 runner 单独用户（甚至单独机器/容器）。

2. 缓存“构建产物”和“依赖仓库”，少碰“全局工具目录”
   例如 ~/.cargo/bin、~/.nvm、~/.pyenv 这种位置，一旦被清理就是系统性故障。

再补一个实用建议：
给 self-hosted runner 加个构建前自检脚本（比如检查 cargo/node/python 是否可用），早失败比跑完才发现要省很多时间。

写在最后

self-hosted 的优势是快、可控、省钱；
代价是你得把“本机”当“生产环境”来管理。

这次问题本身不复杂，但很有代表性：
不是代码错了，是运行边界没隔离好。

如果你也在用 GitHub Actions + self-hosted，建议现在就看一眼你的 workflow：
缓存到底是在加速构建，还是在悄悄改你的机器状态。

本文记录了在实际项目中使用 Cloudflare R2 + Workers 构建软件下载分发体系时，从最初设计、踩坑、排错，到最终稳定方案的完整过程。内容包含 Cache Rules 与 Worker 缓存冲突的真实问题，适合直接作为生产级参考。

一、背景与目标

在为 AirTools 构建桌面端分发体系时，我希望实现：

• 安装包（.exe / .dmg 等）全球 CDN 强缓存
• 版本元信息（latest.json）实时更新、不被缓存
• 不自建服务器，尽量使用 Cloudflare 原生能力
• 缓存行为稳定、可预测，不出现随机 500

最终技术选型为 Cloudflare R2 + Cloudflare Workers。

二、初始架构设计

目标结构如下：

1
2
3
4
5

Client
  ↓
Cloudflare Edge
  ├── latest.json → Worker → R2（不缓存）
  └── *.exe/*.dmg → Worker → R2 → Edge Cache（强缓存）

逻辑上并不复杂，但在实际落地过程中，问题主要集中在 缓存控制细节 上。

三、最早遇到的异常现象

1️⃣ 缓存始终不生效

即便返回了：

1

Cache-Control: public, max-age=2592000, immutable

响应中仍反复出现：

1

cf-cache-status: DYNAMIC

2️⃣ 同一个 URL，返回结果不一致

对同一下载地址多次执行：

1

curl -I https://dl.airtools.app/v0.1.19/AirTools_0.1.19_x64-setup.exe

会出现：

• 有时 200
• 有时 500
• 缓存状态随机变化

这在下载分发场景中是非常危险的信号。

3️⃣ Cloudflare Dashboard 偶发 502

在 Workers / Builds 页面中，Cloudflare 控制台本身也开始报：

1

API Request Failed (502)

这通常意味着某个 Worker 在边缘节点频繁返回 5xx。

四、Cache Rules 带来的隐藏问题（关键）

在排查过程中，一个非常容易被忽略的问题逐渐浮现：Cache Rules 与 Worker 的缓存逻辑发生了冲突。

1️⃣ Cache Rules 的“误导性描述”

Cloudflare Cache Rules 中常见的选项包括：

• 缓存资格（Eligible for cache）
• 绕过缓存（Bypass cache）

这些规则的描述很容易让人误以为：

“只要标记为符合缓存条件，Cloudflare 就一定会缓存”

这是不准确的。

Cache Rules 只是在「是否允许缓存」这一层做判断，真正是否缓存，仍然取决于：

• Worker 中是否使用 cacheEverything
• 返回的 HTTP 状态码是否为 200
• 实际响应头中的 Cache-Control

2️⃣ Cache Rules 覆盖 Worker Header

在早期配置中，我曾在 Cache Rules 中尝试：

• 针对 .exe / .dmg 设置缓存
• 或统一修改 Cache-Control

结果是：

• Worker 返回的 Cache-Control 被规则覆盖
• 错误响应（500）也被错误地标记为可缓存候选
• 实际缓存行为变得不可预测

结论：当请求经过 Worker 时，Cache Rules 很容易成为“干扰项”。

3️⃣ 最终选择：让 Worker 成为唯一缓存决策点

在最终方案中：

• 不再依赖 Cache Rules 控制下载缓存
• Cache Rules 保持最小化甚至删除
• 所有缓存判断统一在 Worker 中完成

这样可以保证：

缓存逻辑是可读的、可调试的、可预测的。

五、真正的根因总结

综合排查后，问题根因集中在三点：

1. Worker 未处理回源失败，导致 500 被返回
2. 500 响应参与缓存资格判断，污染后续请求
3. Cache Rules 与 Worker 缓存逻辑发生冲突

六、最终稳定方案设计

核心原则只有一句话：

只缓存成功的安装包，失败请求永不进入缓存路径

缓存策略表

七、最终 Worker 实现（生产可用）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url)
    const path = url.pathname

    const ORIGIN = 'https://dl.airtools.app'
    const originUrl = ORIGIN + path + url.search

    if (path.endsWith('/latest.json')) {
      let res
      try {
        res = await fetch(originUrl, { cf: { cacheEverything: false } })
      } catch {
        return new Response('Upstream error', { status: 502 })
      }

      const headers = new Headers(res.headers)
      headers.set('Cache-Control', 'no-store, no-cache, must-revalidate')

      return new Response(res.body, { status: res.status, headers })
    }

    const CACHEABLE_EXT = [
      '.dmg', '.exe', '.msi', '.AppImage',
      '.deb', '.rpm', '.zip', '.tar.gz',
      '.sha256', '.sig'
    ]

    const isCacheable = CACHEABLE_EXT.some(ext =>
      path.toLowerCase().endsWith(ext)
    )

    let res
    try {
      res = await fetch(originUrl, {
        cf: {
          cacheEverything: isCacheable,
          cacheTtl: isCacheable ? 60 * 60 * 24 * 30 : undefined
        }
      })
    } catch {
      return new Response('Upstream fetch failed', {
        status: 502,
        headers: { 'Cache-Control': 'no-store' }
      })
    }

    const headers = new Headers(res.headers)

    if (isCacheable && res.status === 200) {
      headers.set('Cache-Control', 'public, max-age=2592000, immutable')
    } else {
      headers.set('Cache-Control', 'no-store, no-cache')
    }

    return new Response(res.body, { status: res.status, headers })
  }
}

八、最终验证结果

• latest.json

  • cf-cache-status: DYNAMIC
  • 实时回源

• 安装包下载

  • cf-cache-status: HIT
  • age 持续增长
  • 支持断点续传

九、经验总结

1. 不要缓存失败响应
2. Worker 必须处理 fetch 异常
3. Cache Rules 不适合与复杂 Worker 缓存逻辑混用
4. 一个域名只承担一种角色（Worker 或 R2）
5. 判断缓存是否生效，以 cf-cache-status 为准

十、结语

Cloudflare R2 + Workers 非常适合用于软件下载分发，但稳定性来自于细节，而不是默认配置。

只要把缓存决策收敛到 Worker 内部，并明确区分“可缓存内容”和“实时内容”，这套架构可以长期稳定运行，且维护成本极低。

比如：
•明明只是想调亮一点，但 RGB/HSL 调完后颜色不是变灰就是变艳；
•做渐变时颜色中途莫名其妙发暗；
•图表配色在亮色主题和暗色主题下反差不一致；
•在宽色域（如 P3）设备上，颜色表现和预期差得更远。

这些都指向同一个底层原因：
RGB（甚至 HSL/HSV）并不是一个符合人眼感知的色彩空间。

于是我开始把新的颜色计算逻辑逐步迁移到 OKLCH —— 一个感知均匀、现代化、已被浏览器原生支持的色彩空间。
这篇文章来分享我为什么做这个选择，也希望给你在项目色彩处理上的参考。

一、RGB / HSL 在实际开发中有哪些明显痛点？

1. RGB 不是为调色设计的

RGB 是硬件色彩空间，核心目的是给屏幕发光，不是为了“符合人眼感知”。

所以你在 RGB 里调亮度，实际上是同时改三个通道，结果往往是“变亮但不自然”。

2. HSL/HSV 看似更直观，但本质还是数学假设

HSL 的亮度是一个简单公式：
L = (max + min) / 2
这与人眼的亮暗感受毫无关系。

所以它经常出现：
•提亮颜色 → 变灰
•调饱和度 → 色相漂移
•淡色系 → 明显“脏”

前端工程师、设计师乃至最近的 AI 图像后处理都会遇到这类问题。

⸻

二、为什么 OKLCH 是更适合现代开发的替代方案？

OKLCH 属于 OKLab 色彩模型的极简表示形式，结构非常简单：
•O：感知亮度
•K：色度（饱和度）
•LCH：和 CIELAB 类似的极坐标表示

它的关键价值可以用一句话总结：

OKLCH 更接近人眼真实的颜色感知，是为现代宽色域、高精度显示时代而设计的。

⸻

三、实际使用中的 5 个核心优势

1. 调色结果更“像人眼认知”

在 OKLCH：
•调亮 → 真的变亮，不变灰
•调饱和度 → 不会突然偏色
•改色相 → 渐变更自然、平滑

只要你写过配色算法，就会立刻感觉到这点的巨大差异。

⸻

2. 渐变、插值更自然

RGB 做渐变常常中间变脏、发黑；
HSL 做渐变色相容易发生折返、跳跃。

OKLCH 解决了这些：
•渐变更线性更均匀
•不会突然暗掉
•更接近真实光学过渡

这点在图表、数据可视化、背景渐变中非常实用。

⸻

3. 在宽色域（P3 / Rec.2020）下表现稳定

很多新设备（Mac、iPhone、现代安卓机）已经进入了 P3 时代，RGB/HSL 的效果在宽色域中更不稳定。

OKLCH 是为这类显示技术设计的：
•高饱和区域不塌陷
•色彩更加一致
•HDR 适配更稳定

对未来兼容性非常友好。

⸻

4. CSS 已经原生支持，迁移成本极低

现在浏览器直接支持：

color: oklch(75% 0.15 240);

不需要 polyfill，也不需要额外库。
迁移甚至可以按需局部替换，成本几乎为零。

⸻

5. 更适合自动化配色、可视化、主题系统

如果你的项目涉及：
•自动生成颜色
•数据可视化（色板、热力图）
•深浅主题适配
•色彩算法
•图像后处理

OKLCH 让这些变得更简单且结果更稳定。

举个例子：
颜色对比度（contrast）可以直接依赖 OKLab 的亮度计算，比 WCAG 的相对亮度公式更准确，也更符合人眼实际观感。

⸻

四、我在自己的项目中是如何使用 OKLCH 的？

我的做法是 从局部渐进迁移：
1.先从需要自动计算的颜色入手（错误提示色、图表颜色、背景色等）
2.再把主题色、渐变色统一写成 OKLCH
3.最后再做一些视觉微调，确保在亮/暗主题都呈现一致对比度

这种方式不需要一次性重构，几乎没有成本压力。

⸻

五、未来为什么需要 OKLCH？

一句话：

未来的显示设备越来越宽色域、越来越精细，RGB/HSL 已经无法满足现代视觉需求。

随着 P3 / HDR 成为主流，颜色系统的基础越靠近视觉生理模型，效果越稳定。
OKLCH 现在能做的事，RGB/HSL 越来越做不到。

⸻

六、总结：为什么值得迁移？

有以下几点
•提高颜色质量的成本极低
•代码更清晰，更接近“亮度/饱和度/色相”的真实含义
•渐变、配色、可视化效果更自然
•兼容性好、未来可扩展
•对项目整体视觉质量有巨大提升

对我来说，迁移到 OKLCH 是一种 小投入、高收益 的技术决策。

本文将介绍如何使用强大的命令行工具 ExifTool 来解决这个问题，包括：
1.为照片添加 GPS 信息；
2.将一张照片的 GPS 信息复制到另一张或多张照片中；
3.检查和验证修改结果。

什么是 ExifTool？

ExifTool 是一款非常强大的命令行工具，可以读取、写入和编辑图片、音视频等文件的元数据（Metadata）。它支持几乎所有的照片格式，包括 JPEG、PNG，以及各大相机品牌的 RAW 格式（NEF、CR2、ARW 等）。

官网地址：https://exiftool.org/

⸻

用 ExifTool 安全地把一张照片的 GPS 信息复制到其它照片（NEF/RAW）——完整实操指南

参考：ExifTool 官方文档 https://exiftool.org/
本文将结论先行：ExifTool 支持直接往 RAW 文件（包括 NEF）写 GPS 信息，并提供默认的 _original 文件自动备份。

⸻

📝 概览（结论先行）
•ExifTool 能够直接写入 RAW（NEF、CR2、ARW 等），GPS 信息可以和 EXIF、XMP 一起保存。
•macOS 上推荐用 Homebrew 安装，也可从 exiftool.org 下载 .pkg。
•操作建议：先备份 → 先验证 → 小规模试运行 → 再批量处理。

⸻

1）准备工作（安装 + 备份）

安装 ExifTool

推荐 Homebrew 安装：

brew install exiftool

或直接下载 Mac 安装包：https://exiftool.org/

验证安装：

exiftool -ver

备份

虽然 ExifTool 默认会保留 _original 文件（参考官方 Backups 说明），但强烈建议在大规模操作前完整复制目录。

⸻

2）读取并验证源文件 GPS 标签

在写入前先确认源文件 GPS 信息存在哪些 group：

显示所有 GPS 相关字段，含组名

exiftool -a -G1 -s -gps* source_with_gps.nef

只看 EXIF GPS

exiftool -gps:all source_with_gps.nef

•-a：显示重复标签•-G1：显示标签组（EXIF、XMP 等）•-s：显示原始标签名

（参见官方 Tag Groups 文档）

⸻

3）单张复制 GPS 信息

把源文件的 GPS 信息复制到目标文件：

exiftool -tagsFromFile source_with_gps.nef -gps:all target_without_gps.nef

•默认会生成 target_without_gps.nef_original（安全备份）。

如果你已确认无误且不需要 _original：

exiftool -P -overwrite_original_in_place
-tagsFromFile source_with_gps.nef -gps:all target_without_gps.nef

•-P：保留文件时间戳•-overwrite_original_in_place：覆盖原文件，并尽量保持文件系统属性（官方 In-place Editing）

⸻

4）批量操作：一张模板 → 整个目录

假设 source.jpg 含 GPS，要把其 GPS 写入当前目录下所有 NEF：

cd /path/to/folder
exiftool -tagsFromFile ../source.jpg -gps:all -ext NEF -r .

解释：
•-ext NEF：只处理 NEF 文件
•-r .：递归处理子目录
•避免 *.*，否则可能匹配 _original 或 .DS_Store 文件（官方 FAQ 有提醒）

覆盖写入（危险操作，需先备份）：

exiftool -P -overwrite_original_in_place
-tagsFromFile ../source.jpg -gps:all -ext NEF -r .

⸻

5）从 XMP Sidecar 导入 GPS

如果 NX Studio 把 GPS 写在 .xmp 文件：

exiftool -tagsFromFile image.nef.xmp -gps:all image.nef

ExifTool 会把 .xmp 里的 GPS 信息同步到 NEF 文件（参考 XMP Tag Handling）。

⸻

6）按 GPX 轨迹打点

若有 GPX 轨迹文件，可根据照片时间自动匹配 GPS：

exiftool -geotag track.gpx *.NEF

支持时区偏移、插值（详见官方 Geotagging 文档）。

⸻

7）手动写入经纬度

如果你手动知道坐标：

exiftool -GPSLatitude=39.9042 -GPSLatitudeRef=N
-GPSLongitude=116.4074 -GPSLongitudeRef=E photo.nef

使用 -n 可避免格式化，直接写入数值。

⸻

8）验证与回滚

验证写入结果

exiftool -a -G1 -s -gps* target.nef

确认 GPSLatitude、GPSLongitude、GPSDateStamp 等标签已写入。

回滚方法
•如果有 _original 文件：手动还原或使用：

exiftool -restore_original target.nef

•若已用 -overwrite_original_in_place：只能依赖事前备份。

⸻

9）常见坑 & 最佳实践

✅ 先备份，再操作
✅ 先测试 2–3 张，再批量运行
✅ 避免 *.*，用 -ext 精确指定文件类型
✅ 注意不同软件读取的 group（EXIF vs XMP）
✅ 保留 _original 是自动安全网

⸻

10）批量脚本示例（macOS / bash）

保存为 copy_gps_from_template.sh，然后：

chmod +x copy_gps_from_template.sh
./copy_gps_from_template.sh source_with_gps.jpg /path/to/target_dir

脚本内容：

#!/usr/bin/env bash
set -euo pipefail

SOURCE=”$1” # 模板文件（有 GPS 的图片）
TARGET_DIR=”$2” # 目标目录
EXT=”NEF” # 要处理的扩展名

if [ -z “$SOURCE” ] || [ -z “$TARGET_DIR” ]; then
echo “Usage: $0 “
exit 1
fi

echo “Dry-run: files that WOULD be processed:”
find “$TARGET_DIR” -type f -iname “*.${EXT}” -print | sed -n ‘1,50p’
echo “—-“
echo “To actually run, edit script and uncomment exiftool command.”

实际运行（保留 _original）

exiftool -tagsFromFile “$SOURCE” -gps:all -ext “$EXT” -r “$TARGET_DIR”

覆盖原文件（危险）

OVERWRITE_FLAGS=”-P -overwrite_original_in_place”

exiftool $OVERWRITE_FLAGS -tagsFromFile “$SOURCE” -gps:all -ext “$EXT” -r “$TARGET_DIR”

echo “Done. Verify with: exiftool -a -G1 -s -gps* “

⸻

📌 总结
•ExifTool 是处理照片 GPS 信息的标准工具。
•既可以从一张“模板”照片复制 GPS，也可以从 XMP sidecar 或 GPX 轨迹导入。
•默认 _original 文件机制提供了安全保障，建议初期不要关闭。
•批量处理时，要谨慎，推荐小规模试运行。

⸻

要不要我帮你再写一份 针对“先小规模测试 → 大规模批处理”的实操清单（比如一个三步 checklist，你只要按顺序执行，就能避免 90% 的坑）？

Docker 镜像加速器是由国内服务提供商搭建的镜像仓库，通过同步 Docker Hub 的内容，提供更快的镜像拉取速度。这些加速器能够有效减少镜像下载时间，提高开发和部署效率。

常用的国内 Docker 镜像加速器

以下是一些常用的国内 Docker 镜像加速器：

•https://cr.laoyou.ip-ddns.com
•https://docker.1panel.live
•https://image.cloudlayer.icu
•https://hub.fast360.xyz
•https://docker-0.unsee.tech
•https://docker.1panelproxy.com
•https://docker.tbedu.top
•https://dockerpull.cn
•https://docker.m.daocloud.io
•https://hub.rat.dev
•https://docker.kejilion.pro
•https://docker.hlmirror.com
•https://docker.imgdb.de
•https://docker.melikeme.cn
•https://ccr.ccs.tencentyun.com
•https://pull.loridocker.com

要配置 Docker 使用上述镜像加速器，可以按照以下步骤进行：
1. 创建或编辑 Docker 配置文件：在终端中执行以下命令：

 sudo mkdir -p /etc/dockersudo tee /etc/docker/daemon.json <<-'EOF'{    "registry-mirrors": [        "https://cr.laoyou.ip-ddns.com",        "https://docker.1panel.live",        "https://image.cloudlayer.icu",        "https://hub.fast360.xyz",        "https://docker-0.unsee.tech",        "https://docker.1panelproxy.com",        "https://docker.tbedu.top",        "https://dockerpull.cn",        "https://docker.m.daocloud.io",        "https://hub.rat.dev",        "https://docker.kejilion.pro",        "https://docker.hlmirror.com",        "https://docker.imgdb.de",        "https://docker.melikeme.cn",        "https://ccr.ccs.tencentyun.com",        "https://pull.loridocker.com"    ]}EOF

1. 重启 Docker 服务：使配置生效：

   1 2 3 4 5 6

   sudo systemctl daemon-reload sudo systemctl restart docker 1. 验证配置：使用以下命令检查配置是否生效： ```bash docker info

   在输出中，应看到类似以下内容：

   1 2 3 4

   Registry Mirrors: https://cr.laoyou.ip-ddns.com/ https://docker.1panel.live/ ...

这表明 Docker 已成功配置了国内镜像加速器。
注意事项

•镜像加速器的可用性：由于网络环境和服务提供商的维护情况，镜像加速器的可用性可能会发生变化。建议定期检查并更新配置，以确保使用的镜像加速器稳定可靠。•安全性考虑：使用镜像加速器时，应选择信誉良好的服务提供商，以确保镜像的完整性和安全性。

1. 核心功能与支持格式

MarkItDown 支持广泛的文件类型转换，覆盖了办公、多媒体及常见文本格式：

• 办公文档：PDF（提取结构化内容）、Word（保留基础格式和注释）、Excel（表格转Markdown表格）、PowerPoint（提取幻灯片文本和图表）。
• 图像与音频：提取 EXIF 元数据、OCR 文字识别（图片）、语音转文本（音频）。
• 其他格式：HTML（优化维基百科等复杂页面）、CSV/JSON/XML（结构化数据转Markdown）、ZIP 压缩包（批量处理内部文件）。
• AI 集成：支持调用 OpenAI 等大语言模型（如 GPT-4），为图片生成描述性文本或增强语义分析。

2. 技术实现与依赖库

MarkItDown 基于模块化设计，整合了多个高效的开源库以实现复杂文件处理：

• 文档解析：
  • PDF 使用 pdfminer.six 提取文本，Word 依赖 mammoth，Excel 基于 openpyxl，PPT 使用 python-pptx。
  • HTML 通过 beautifulsoup4 和 markdownify 清理并转换格式。
• 多媒体处理：
  • 音频转文本通过 SpeechRecognition 库实现，OCR 使用 EasyOCR。
  • 图像描述需配置 ExifTool（元数据提取）和 LLM（如 OpenAI 的 GPT-4）。
• 其他工具：
  • 字符编码处理依赖 charset-normalizer，文件类型检测使用 puremagic。

3. 应用场景与优劣

MarkItDown 的灵活性和高效性使其在多个领域发挥作用：

• 自动化文档管理：批量转换混合格式文件为统一 Markdown，便于版本控制或知识库构建。
• AI 数据预处理：将非结构化数据（如 PDF、音频）转换为可分析的文本，提升大语言模型训练效率。
• 无障碍支持：转录音频内容为文本，或从图像中提取文字，助力无障碍工作流。
• 开发与协作：开发者可快速提取文档内容进行索引或分析，团队协作中 Markdown 格式更易维护。
• 劣势：不支持doc和xls等前一代的Office格式，对于PDF中的图片也没有办法，甚至PDF过大也不行。

4. 开源与社区支持

• 开源协议：遵循 MIT 许可证，允许自由使用、修改和分发，需保留原始版权声明。
• 社区贡献：微软鼓励开发者参与插件开发（支持第三方扩展）及问题修复，GitHub 提供详细贡献指南和测试框架。
• 持续优化：用户反馈的已知问题（如图片转换失败、PDF 编码错误）正在逐步解决。

倔强要来的娃
让我多了一个身份
家庭多了一个成员
软萌可爱
却又有时脾气恶劣
天使魔鬼结合体

从看到娃的那时起
软肋铠甲并存
想了太多太多
她嫌我想的太远
我却不知道能否保证娃的健康快乐

因为娃
我跟她疲惫不堪
得靠着娃的笑容充电

值么？
不知道
但
也没得选
对么？

2024年的如今一团糟
2025年的以后还会更糟么？

ORJSON 是一个超快速且功能丰富的 JSON 解析和序列化库，它利用 Rust 实现，性能显著优于 Python 标准库和其他 JSON 库（如 ujson 和 rapidjson）。

ORJSON 的优势

1. 高性能：在序列化和反序列化速度上，ORJSON 是当前最快的 Python JSON 库之一。
2. 支持复杂数据类型：原生支持 datetime、numpy 数组等复杂数据类型的序列化，而无需额外处理。
3. 严格的标准化支持：ORJSON 完全符合 JSON 标准，并支持 UTF-8 编码。
4. 易用性：API 设计简单直观，几乎可以直接替换标准库 json 模块的功能。

安装 ORJSON

在项目中安装 ORJSON 非常简单，只需运行以下命令：

1

pip install orjson

ORJSON 基本用法

1. JSON 序列化

ORJSON 的序列化使用 orjson.dumps 函数，返回的结果是字节类型（bytes），可以轻松用于文件写入或网络传输。

1
2
3
4
5
6
7
8

import orjson

# 示例数据
data = {"name": "Alice", "age": 25, "is_student": False}

# 序列化为 JSON 字节串
json_bytes = orjson.dumps(data)
print(json_bytes.decode("utf-8"))  # 转换为字符串输出

输出：

1

{"name":"Alice","age":25,"is_student":false}

2. JSON 反序列化

ORJSON 的反序列化使用 orjson.loads，可以将 JSON 字符串或字节串快速解析为 Python 对象。

1
2
3

json_data = b'{"name":"Alice","age":25,"is_student":false}'
parsed_data = orjson.loads(json_data)
print(parsed_data)

输出：

1

{'name': 'Alice', 'age': 25, 'is_student': False}

3. 处理日期和时间

ORJSON 支持直接序列化 datetime 对象，无需额外格式化。

1
2
3
4
5
6
7
8

import orjson
from datetime import datetime

data = {"timestamp": datetime.utcnow()}

# 序列化
json_bytes = orjson.dumps(data, option=orjson.OPT_NAIVE_UTC)
print(json_bytes.decode("utf-8"))

输出：

1

{"timestamp":"2024-12-18T10:15:30.000000Z"}

性能对比

以下是 ORJSON 与其他 JSON 库的简单性能对比（序列化 100 万条数据）：

从表中可以看出，ORJSON 的性能显著优于其他库，非常适合大数据量的 JSON 操作。

总结

ORJSON 是一款性能卓越的 JSON 库，它以极快的速度、简洁的 API 和出色的功能支持，成为处理 JSON 数据的理想选择。

可以在 ORJSON 的官方文档 中了解更多细节。

1
2

app = Flask（__name__）
app.config［'JSON_AS_ASCII'］ = False ＃ 解决中文乱码问题

但是最新的不行了

针对版本的检查，是新版本弃用上面的方法了，新版本的如下
Flask 2.3.0以上

1
2

app = Flask（__name__）
app.json.ensure_ascii = False # 解决中文乱码问题

Flask 2.2.5以下

1
2

app = Flask（__name__）
app.config［'JSON_AS_ASCII'］ = False # 解决中文乱码问题

到孕期各种检查，身体不舒服；

到终于的生出来的那一刻；

不能说五味杂陈，只能说感慨颇多。

小家伙在肚子里面的时候，就是一个调皮的娃，各种扑腾。

家里人问我们起名字，我们商量好了，写几个名字，让小家伙到时候自己抓一个就行。

本来要等40周，可惜检查的时候医生说生长太慢了，就提前入院，检查，打针，等待，然后生产。好歹整个过程还算顺利。

等待的时候，护士问她要不要让我陪产，她说我害怕，就别让我进来了。我犹豫了半天，终于还是进去了。不知道怎么形容整个过程，她说我的汗比她还多。

生出来之后，医生没有让我剪脐带，但是登记好之后，让我抱抱小家伙。

一到手里，第一感觉，沉甸甸的小家伙。满身胎脂，眼睛看来看去，动来动去的，看着真的是让人开心，非常单纯得开心。

但其实到现在还是没感觉到什么父爱，问她也不知道啥叫母爱。小家伙从最开始哼哼唧唧，到后来饿得难受，哭得那个样子，看得人确实心疼。两个人在医院真的被小家伙折磨够呛，虽然已经算很乖的宝宝了，但是哭、闹、哼哼唧唧都让两个人没法彻底睡着。

都在慢慢学着哄娃，出生之前跟小家伙说，只希望你健康。

现在看着小家伙熟睡样子，加一句，希望你健康，也希望你快乐。

• 隔离项目依赖项： 每个项目可能需要不同的库和 Python 版本。通过使用虚拟环境，可以将每个项目的依赖项隔离在自己的环境中，避免冲突和版本问题。
• 提高开发效率： 虚拟环境可以让你快速地在不同的项目之间切换，而无需担心依赖项冲突或版本问题。
• 简化部署： 如果你将项目部署到不同的服务器上，那么你可以使用虚拟环境来确保每个服务器上都安装了正确的依赖项。
• 提高安全性： 虚拟环境可以帮助开发者隔离不安全的代码或库，防止它们影响其他项目或系统。

现在Python环境有三个用的比较多的，分别是
• virtualenv
• ven
• pipenv

联系

• virtualenv、venv 和 pipenv 都是 Python 的虚拟环境管理工具。
• 它们都可以用来创建和管理独立的 Python 环境，可以在不同的项目中使用不同的 Python版本和库。

区别

• virtualenv 是最古老的 Python 虚拟环境管理工具。它需要开发者明确地创建和管理虚拟环境。
• venv 是 Python 3.3 中内置的虚拟环境管理工具。它比 virtualenv 更易于使用，因为它不需要你明确地创建和管理虚拟环境。
• pipenv 是一个更高级的 Python 虚拟环境管理工具。它不仅可以创建和管理虚拟环境，还可以管理项目依赖项。

表格对比：

总体来说，如果只是想创建一个独立的 Python 环境，那么 venv 是一个不错的选择。如果想管理项目依赖项，那么 pipenv 是一个更好的选择。

何时使用

何时使用 virtualenv、venv 或 pipenv？

• 使用 virtualenv：
• 需要对虚拟环境有更精细的控制。
• 需要在旧版本的 Python 上创建虚拟环境。
• 使用 venv：
• 想轻松地创建和管理虚拟环境。
• 不需要管理项目依赖项。
• 使用 pipenv：
• 想管理项目依赖项。
• 想要一个更易于使用的虚拟环境管理工具。

请注意，pipenv 仍然是一个相对较新的工具，可能不如 virtualenv 和 venv 稳定。但是，它具有许多有用的特性，并且正在迅速发展。