最近在折腾 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 稳定。但是，它具有许多有用的特性，并且正在迅速发展。

方式一：临时使用

1. 在终端中输入以下命令：

1

npm --registry https://registry.npmmirror.com install [模块名]

如果安装成功，则表示设置成功。

方式二：修改本地配置，永久生效

1. 在终端中输入以下命令：

1

npm config set registry https://registry.npmmirror.com

2. 输入以下命令确认设置是否成功：

1

npm config get registry

如果输出结果为 https://registry.npmmirror.com，则表示设置成功。

无论使用哪种方式，都可以解决大陆服务器有时会拉取模块不通畅的问题。

注意：

• 如果需要恢复到默认的 npm 源，可以使用以下命令：

1

npm config set registry https://registry.npmjs.org

npmmirror 镜像站

点击添加容器

源：cnk3x/xunlei:latest

网络类型选择bridge

添加data和downloads两个映射目录，和2345端口

重点：要开启“特权”

否则会报错，具体的如下：

如果还想希望加上图标，则按图点击

然后在图标网址填写如下：
https://cdn.jsdelivr.net/gh/xushier/HD-Icons@master/border-radius/Xunlei_A.png

在哪里安装Docker

unRAID 提供了一个叫做 APPS全称叫做 Community Applications（社区应用，简称为 CA），用户可以在里面搜索到相应的插件、Docker 等进行安装。

直接在里面搜索TinyMediaManager ，但是发现只有两个镜像，一个还是v3版本的，所以我们需要手动安装

手动安装

可以点击右侧的“单击此处以从 DockerHub 获取更多结果”来展示 Docker Hub 所搜索到的内容：

当你点击“安装”按钮之后，unRAID 会先拉取 Docker 镜像，然后会尝试自动给你添加相应的参数：

推荐配置

此处直接推荐dzhuang的镜像tinymediamanager4-docker ，不过V4介绍说明有点错误，详情直接参考下图

自定义图标

编辑Docker镜像，然后点击如图位置

图标我选择的是如下：https://cdn.jsdelivr.net/gh/xushier/HD-Icons@master/border-radius/Tmm_A.png
如果不喜欢，可以在这个地址下找到自己喜欢的：GitHub - xushier/HD-Icons: 高清仪表盘图标（1024x1024 分辨率）
然后点击最下面的确定即可。