豕豕豕 - Blog

在 Mac 上原生玩《王国之泪》：MacNativeGames 构建与使用教程

Thu, 22 Oct 2026 00:00:00 GMT

想在 Mac 上玩《王国之泪》，现在可以试试 MacNativeGames。它会处理你提供的游戏文件，将游戏的 ARM64 代码适配到 Apple 芯片上运行，再通过 Metal 完成图形渲染，最后打包成一个可以从访达打开的 Mac App。准备工作主要集中在第一次构建，之后启动游戏就方便多了。

这篇教程面向平时会用 Mac、但不一定熟悉编译工具的玩家。从安装依赖开始，一步步完成本体或更新版的构建，再处理操作、画面和存档。本文只讲 Mac 版。

本文对应的版本

本文于 2026 年 10 月 22 日整理，依据项目提交 30a1b93 的说明与构建脚本。下文固定使用这份源码，方便核对操作。后续版本的要求和按键可能变化，使用新版时请同时查看它的 README。本文核对了文档和命令参数，没有重新完成一次全量游戏构建，也没有做性能基准测试。

1. 开始之前，先确认这些条件

机器与空间

项目	要求
Mac	Apple 芯片机型，如 M1、M2、M3、M4、M5；本文流程不适用于 Intel Mac
系统	macOS 26 或更高，使用项目的 Metal 4 图形后端
内存	项目建议 16 GB 或更多；8 GB 机型构建时可能大量使用交换空间
存储	本体构建除原始游戏文件外约需 25 GB；全新本体加更新构建约需 40 GB
网络	安装依赖、获取构建所需的固定版本源码时需要联网

上面的空间估算以工作目录和成品 App 位于同一个 APFS 卷为前提。构建器可以通过 APFS 克隆共享大型数据文件；输出到其他卷，或文件系统不支持克隆时，还要为 App 副本额外预留约 17 GB。空间紧张时，先把磁盘整理好再开始。

游戏文件

准备以下文件：

自己的《王国之泪》1.0.0 本体，格式为未压缩的 XCI 或 NSP，标题 ID 为 0100F2C0115B6000。
自己的 prod.keys。
如果要构建更新版，再准备一份独立的累计更新包，支持 1.1.2、1.2.1、1.4.3，格式为 NSP 或 NSZ。
使用 NSP 本体时，还需准备系统共享字体，具体见后文。

文件来源与成品使用

按项目要求，游戏、密钥及系统文件应来自你自己拥有的游戏和 Switch。仓库没有提供这些内容，本文也不提供下载来源。构建出的 App 包含游戏内容，请留作个人使用，不要分享成品 App。

本体 NSZ/XCZ、DLC、合并包和个性化票据不在本文所用版本的支持范围内。 更新包可以是 NSZ，不代表本体也可以直接使用 NSZ。构建 1.4.3 时，给出 1.0.0 本体和 1.4.3 的独立累计更新即可，不需要逐个安装中间版本。

2. 安装构建工具

打开 macOS 的“终端”，先安装 Xcode 命令行工具：

xcode-select --install

如果系统提示已经安装，直接继续；如果出现安装窗口，等安装结束再执行后面的命令。

接着安装 Homebrew。按照官网的步骤操作，并完成安装器最后给出的 shell 配置。Apple 芯片 Mac 的默认安装位置是 /opt/homebrew，具体说明见 Homebrew 安装文档。

确认终端能找到 Homebrew，再安装依赖：

brew --version
brew install opus libvpx python@3.14
python3.14 --version

最后一条应显示 Python 3.14.x。后面的命令统一使用 python3.14，避免误用系统自带或其他版本的 Python。

这一版的 Mac 构建流程不要求安装 .NET、CMake 或 iOS 工具链。脚本会继续准备自身需要的环境，完成后的 App 运行时也不需要 Python。

可选：安装 Metal 工具链

如果已经安装完整 Xcode，可以按照 Apple 的附加组件说明安装 Metal 工具链：

xcodebuild -downloadComponent MetalToolchain

项目会利用它将启动着色器预编译进 App。只有命令行工具、没有完整 Xcode 时，可以先跳过这一项：构建仍能进行，只是着色器预编译会使用本机、对应 App 路径的 Metal 缓存。后面移动 App 时，两种方式的差别就会体现出来。

3. 下载源码，整理文件

下面把源码放在 ~/Projects。如果你已经在其他位置下载过，可以直接进入自己的项目目录。

mkdir -p "$HOME/Projects"
cd "$HOME/Projects"
git clone https://github.com/ly05010419/MacNativeGames.git
cd MacNativeGames
git checkout 30a1b93d0776150fbaffd7c20f9a5ca0841c21c9

最后一条将源码切到本文使用的提交。Git 可能提示 detached HEAD，这是查看固定提交时的正常状态，不影响构建。

为了方便看懂命令，后文约定文件像这样摆放，文件名只是示例，请替换成你的实际路径：

~/Games/TOTK/
  base.xci            本体；使用 NSP 时为 base.nsp
  update-1.4.3.nsp     可选的独立更新包
  firmware/           NSP 路线需要，内部是解包后的 .nca 文件

~/keys/
  prod.keys

再创建用户自己的应用目录，把成品直接构建到这里：

mkdir -p "$HOME/Applications"

~/Applications 在你的用户目录下，与系统的 /Applications 是两个位置。本文使用前者，通常不需要管理员权限。提前确定输出位置，也能减少日后移动 App 引起的着色器缓存重建。

路径里有空格怎么办

把完整路径放进双引号，例如 "$HOME/Games/TOTK/My Game.xci"。也可以把文件从访达拖进终端插入路径。注意双引号里的 ~ 不会自动展开，因此本文统一写成 "$HOME/..."。

4. 选择一条构建命令

以下命令都在刚才的 MacNativeGames 源码目录中运行。按自己的文件情况选一条即可，不需要依次执行。

XCI 本体：先构建 1.0.0

python3.14 build_app.py "$HOME/Games/TOTK/base.xci" \
  -k "$HOME/keys/prod.keys" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

这会构建 1.0.0。通常 XCI 中的系统更新分区能提供共享字体；如果你的 XCI 缺少该分区，也要像下一节那样添加 --firmware 或 --shared-fonts。

NSP 本体：额外提供字体

NSP 本体不带系统共享字体，因此要额外传入已经解包的固件目录：

python3.14 build_app.py "$HOME/Games/TOTK/base.nsp" \
  -k "$HOME/keys/prod.keys" \
  --firmware "$HOME/Games/TOTK/firmware" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

这里的 firmware 应当是包含 .nca 文件的目录，也可以是已安装固件的 registered 目录。不要把固件 ZIP 压缩包直接传给它。

如果以前成功提取过字体，可以把 --firmware 换成：

--shared-fonts "$HOME/Games/TOTK/TOTK_build/totk/extracted/firmware/shared-fonts"

上面是用于替换的参数片段，不是单独执行的命令。它指向的目录需要包含 0-standard.bfttf 至 5-nintendo-extension.bfttf 六个字体。构建器会校验文件，也会复用工作目录内已经有效的字体，不必手动改成系统上的普通字体。

本体加更新：以 1.4.3 为例

XCI 本体加独立更新包：

python3.14 build_app.py "$HOME/Games/TOTK/base.xci" \
  -k "$HOME/keys/prod.keys" \
  --update "$HOME/Games/TOTK/update-1.4.3.nsp" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

如果本体是 NSP，完整命令为：

python3.14 build_app.py "$HOME/Games/TOTK/base.nsp" \
  -k "$HOME/keys/prod.keys" \
  --firmware "$HOME/Games/TOTK/firmware" \
  --update "$HOME/Games/TOTK/update-1.4.3.nsp" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

更新包为 NSZ 时，将 --update 后的路径换成对应 .nsz 文件即可；构建器会处理解压和校验。要构建 1.1.2 或 1.2.1，则换成相应版本的累计更新包。省略 --update 就是构建 1.0.0，不会自动选择更新。

几个参数可以这样记：

参数	作用
`build_app.py` 后的文件路径	1.0.0 本体
`-k`	密钥文件
`--update`	可选的独立累计更新包
`--firmware` / `--shared-fonts`	二选一提供字体来源
`-o`	成品 App 的完整路径，需要以 `.app` 结尾
`--work`	可选，自定义中间文件目录

如果不传 -o，成品默认放在本体文件旁边。按本文摆放文件时，默认工作目录是 ~/Games/TOTK/TOTK_build，其中保存提取结果和构建日志。中途遇到可修复的问题，处理后重新运行原命令即可复用已经完成的步骤，先别急着删除整个目录。

构建期间需要等多久

脚本会提取并校验游戏数据、改写程序模块、准备着色器，最后完成打包和签名。终端继续输出进度时，先让它跑完。首次构建受机器内存、磁盘和网络影响很大，着色器编译尤其可能耗时。

项目记录中，8 GB 的 M1 MacBook Air 仅 GPU 着色器编译这一步就可能花约 25 分钟。这只能帮助判断“为什么还没结束”，不能用作你的整次构建耗时预估。

构建完成时，脚本会以 --check 模式检查启动器。这表示可执行文件检查等步骤完成，还需要实际打开游戏，确认画面、声音和操作。

5. 第一次启动，先让它准备好

打开访达，按 Command + Shift + G，输入 ~/Applications，双击 Tears of the Kingdom.app。也可以从终端启动：

open "$HOME/Applications/Tears of the Kingdom.app"

首次启动会校验游戏数据并准备着色器。项目在本地观察到数据校验约需 20 秒，实际等待时间取决于机器和缓存状态。看到进度提示时，先等它完成。

到达标题画面后，其余着色器仍可能在后台预热，第一次进入世界时还可能继续等待。构建器已经从你的游戏数据和公共着色器清单生成首启所需内容，通常不需要另找一份别人分享的缓存。

进入没有走过的场景，仍可能遇到新的着色器变体并短暂卡顿。首次编译与持续低帧率是两种情况：如果同一处第二次经过明显改善，缓存已经发挥作用；如果一直很慢，就要继续看画面设置、内存和具体场景。

App 可以移动吗

可以，但最好在构建前就确定位置：

装有 Metal 工具链： 预编译内容随 App 打包，移动后仍能利用这部分内容。
没有 Metal 工具链： 本机 Metal 缓存与 App 的位置有关，挪动后可能重新编译。系统清理缓存后也可能发生类似情况。

这也是本文直接用 -o 构建到最终目录的原因。跨卷复制还可能多占一份游戏数据空间，并让 macOS 再次检查 App。

6. 手柄与键盘操作

手柄：先留意确认键的位置

macOS 能识别的兼容手柄，例如 DualSense 和 Xbox 手柄，会映射为 Switch Pro 手柄。默认布局按正面按键的位置对应：

手柄上的位置	Switch 按键	Xbox	PlayStation
右侧	A：确认、互动	B	圆圈
下方	B：取消、冲刺	A	叉
上方	X：跳跃	Y	三角
左侧	Y：攻击	X	方块

因此，拿 Xbox 手柄看到游戏提示“按 A”时，默认要按右侧的 B。体感和震动能否工作，还取决于手柄本身及 macOS 是否提供相应能力。

需要自定义手柄映射时，配置文件在：

~/Library/Application Support/MacNativeGames/TOTK/controls.txt

例如，给 DualSense 的触摸板点击分配地图键：

touchpad = minus

未写出的按键继续使用默认值。修改后重启游戏；如果启动器提示某一行配置有误，按提示检查该行。删除这份配置文件可以恢复默认映射。

键盘：本文固定版本的布局

下面是本文提交版本的默认键盘映射，按键按美式键盘物理位置识别。使用其他版本时，以对应 README 和游戏内快捷键提示为准。

Mac 按键	操作
W、A、S、D	移动，左摇杆
方向键	转动视角，右摇杆
J	A：确认、互动
K 或空格	B：取消、冲刺
I	X：跳跃
U	Y：攻击
Q / E	L / R
Option / Shift	ZL / ZR
F、T、H、G	十字键左、上、右、下
Z / C	按下左摇杆 / 右摇杆
Return	菜单（+）
Tab 或 Esc	地图（−）

7. 画面设置，一次调整一项

先用默认画面进入游戏，确认基础操作正常，再试下面的数字键。这样更容易判断是哪一项设置带来了变化。

按键	作用
1	切换完整信息面板、仅 FPS、全部隐藏
2	切换补帧模式：关闭、30+30、半刷新率、无限制
3	切换 MetalFX 2K、原生 2K、关闭
4	切换 `16:9`、适配窗口或显示器、`21:9`；限 1.2.1 / 1.4.3
5	开关 MetalFX 时间性抗锯齿；限 1.4.3

这里有两点容易误会：

补帧显示的帧数包含生成帧，不能直接当作游戏逻辑运行帧率。
“原生 2K”会调整合成画布与 UI，但 3D 场景仍有单独的渲染缩放，不能据此认为所有内部渲染目标都固定为 1440p。

游戏默认跟随 Mac 的语言。如果想临时指定游戏为简体中文，先完全退出游戏，再运行：

open --env TOTK_LANG=zh-Hans "$HOME/Applications/Tears of the Kingdom.app"

这是本次启动的环境变量。已经运行的 App 不会因为再次执行 open 就重新读取这些启动参数。

8. 存档在哪里，更新前怎么备份

成品 App、构建工作目录和个人存档是三处不同的东西：

内容	位置
本文的成品 App	`~/Applications/Tears of the Kingdom.app`
本文的默认工作目录	`~/Games/TOTK/TOTK_build`
存档 profile	`~/Library/Application Support/MacNativeGames/TOTK/profile`
着色器缓存	`~/Library/Application Support/MacNativeGames/TOTK/shader-cache`
本次运行日志	`~/Library/Logs/MacNativeGames/totk.log`
上次运行日志	`~/Library/Logs/MacNativeGames/totk.previous.log`

在访达里按 Command + Shift + G 就能进入这些目录。

更换游戏版本前，先退出游戏，再把整个 profile 文件夹复制到别处备份。启动更新版时，项目还会在 profile 旁创建对应的升级前备份，例如 profile-before-1.4.3；备份失败则停止启动。不要假设新版保存过的进度能被旧版读取，回退时应保留升级前的那份备份。

更新项目代码时，获取你要使用的新版源码，再用原始本体、相同的更新包和输出路径重新构建。先退出正在运行的游戏，并保留原先的 --firmware、--shared-fonts、--work 等必要参数。重新构建到相同路径会替换原 App；存档在上面的用户目录里独立保存。

9. 常见问题

提示找不到 `brew` 或 `python3.14`

先检查 Homebrew 安装器要求的 shell 配置是否完成，重新打开终端，再执行第二节的版本检查。即使机器上有 python3，也不代表它就是 Python 3.14。使用 Apple 芯片版本的 Homebrew，避免把另一套 Intel 环境的依赖混进来。

提示缺少 shared fonts

先看本体是不是 NSP。NSP 要传 --firmware 或 --shared-fonts；缺少系统更新分区的 XCI 也需要。确认传入的是解包后的目录，字体目录则应包含六个 .bfttf 文件。

提示版本或哈希不匹配

核对本体是否为 1.0.0，更新包是否为受支持的独立累计更新，文件是否完整，以及密钥是否与自己的内容相符。构建器的校验用于发现不受支持或损坏的输入，不要通过修改预期哈希跳过错误。

双击后迟迟没有游戏窗口

首次启动、移动 App 或跨卷复制后，可能正在进行系统检查或数据校验。先观察进度与日志；如果已经弹出明确错误，就按错误处理。构建阶段的 --check 成功，只说明启动检查完成，不能替代真实游玩验证。

一直卡顿，或者内存压力很大

先关闭其他占用大量内存的程序，查看“活动监视器”的内存压力与交换空间。用 3 键关闭额外的 2K 模式作对照，等后台预热完成，再测试同一场景。不要一边首次编译一边判断整台机器的最终性能，也不必把“删除全部缓存”当作常规优化：缓存删掉后需要重新准备。

有音效，但对白或背景音乐不正常

先确认 macOS 当前音频输出设备和音量，再检查日志中的 CoreAudio 或解码错误。项目已有针对流式音频路径的修复，可参考音频排障文档。仍在使用早期 App 时，用包含修复的源码和原始游戏文件重新构建；着色器编译造成的瞬间停顿也可能打断声音，需要分开判断。

想安装 MOD

先完成一次无 MOD 的构建和启动。之后按项目的 MOD 文档操作：代码补丁通过构建时的 --mod 合入，RomFS 数据文件另有安装和清单要求。不要把其他环境里的 MOD 文件夹直接扔进 App 包。

参考资料

在你的 Linux 服务器上部署 Xboard 实现自建机场

Mon, 22 Jun 2026 00:00:00 GMT

这篇教程源于我最近的一次从零搭建 Xboard 面板、Caddy HTTPS、Hysteria2 节点、订阅域名、SMTP 邮件和上线收口的完整过程。

适合你的场景是：你有一台公网 Linux 服务器部署 Xboard 面板，再用一台或多台 Linux VPS 作为节点。当然 Xboard 部署在本地也不是大问题，但至少要有一台海外服务器承接节点。

准备清单

开工前，建议先把下面这些东西准备齐：

一台面板服务器：Ubuntu 22.04 / 24.04 或 Debian 12，建议 1GB 内存起步，2GB 更稳，需要开放 80/tcp 和 443/tcp。
一台或多台节点服务器：Ubuntu 22.04 / 24.04 或 Debian 12，协议使用 Hysteria2，需要开放 8443/udp，或者后续使用端口跳跃时开放 20000-29999/udp。
一组拆开的域名：一个面板域名、一个订阅域名、一个或多个节点域名。
Cloudflare DNS 管理权限：本文示例全部基于 Cloudflare 做 DNS 管理。
一个 SMTP 发信服务：这里使用 Brevo 免费 SMTP。
一个可接收验证邮件的邮箱入口：这里配合 Cloudflare Email Routing 使用。
基础系统工具：curl、wget、git、ufw，以及后续要安装的 Docker、Caddy、certbot。

本文示例域名如下：

面板域名：v.shishishi3.com
订阅域名：474769754.xyz
香港节点：hk.474769754.xyz
美国节点：us.474769754.xyz

实际使用时替换成你自己的域名。

架构图

本文采用直接的 Linux 部署方式：

用户 -> 域名 HTTPS -> Linux 服务器 Caddy -> Xboard 容器
用户 -> HY2 节点域名 UDP -> Linux 节点服务器 xboard-node

推荐把域名职责拆开：

v.shishishi3.com
用途：Xboard 主面板、后台登录、管理员操作

474769754.xyz
用途：订阅分发入口

hk.474769754.xyz
用途：香港节点域名

us.474769754.xyz
用途：美国节点域名

说明

不建议用同一个域名同时做后台、订阅和节点。分开之后排错和风控都清爽很多，同时也能降低某一项业务出问题后连带影响其他业务的风险。

如果你打算把订阅入口单独拆出来，买一个纯数字域名通常就够用了，一般不会超过 ¥10。

正式教程

1. 服务器准备

面板服务器建议：

系统：Ubuntu 22.04 / 24.04 或 Debian 12
内存：1GB 起，2GB 更稳
端口：80/tcp, 443/tcp

节点服务器建议：

系统：Ubuntu 22.04 / 24.04 或 Debian 12
协议：Hysteria2
端口：8443/udp，或端口跳跃 20000-29999/udp

先更新系统：

sudo apt-get update
sudo apt-get install -y curl wget ca-certificates git ufw

排错

如果这里因为之前安装过 Ookla speedtest 源报错卡住，直接跳到系统 apt 源报错。

2. DNS 配置

Cloudflare DNS 示例：

A  v    面板服务器 IP  DNS only
A  @    面板服务器 IP  DNS only
A  hk   香港节点 IP    DNS only
A  us   美国节点 IP    DNS only

重点：

根域名 474769754.xyz 的主机名要填 @，不是填 474769754。
节点域名必须灰云，也就是 DNS only，不要橙云。
HY2 走 UDP，Cloudflare 普通代理不转发这种流量。
DNS 刚改完可能要等几分钟。

验证：

nslookup 474769754.xyz 1.1.1.1
nslookup hk.474769754.xyz 1.1.1.1
nslookup us.474769754.xyz 1.1.1.1

排错

如果你本机开了代理或 TUN，看到了 198.18.x.x 这种 fake-ip，跳到 DNS 被 fake-ip 干扰。

3. 安装 Docker 与 Compose

如果服务器还没有 Docker：

curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker
docker --version
docker compose version

4. 部署 Xboard

Xboard 官方 compose 分支提供了 Docker Compose 模板，默认把容器 7001 暴露到宿主机 7001。

cd /opt
sudo git clone -b compose --depth 1 https://github.com/cedar2025/Xboard Xboard
cd /opt/Xboard

确认 compose.yaml 里有类似配置：

services:
  xboard:
    image: ghcr.io/cedar2025/xboard:latest
    restart: unless-stopped
    ports:
      - "7001:7001"
    volumes:
      - ./.env:/www/.env
      - ./.docker/.data/:/www/.docker/.data
      - ./storage/logs:/www/storage/logs
      - ./storage/theme:/www/storage/theme
      - ./plugins:/www/plugins
      - redis-data:/data

初始化安装，推荐 SQLite + 内置 Redis，简单好维护：

sudo docker compose run --rm \
  -e ENABLE_SQLITE=true \
  -e ENABLE_REDIS=true \
  -e ADMIN_ACCOUNT=admin@example.com \
  xboard php artisan xboard:install

安装完成后会输出：

管理员邮箱
管理员密码
后台路径

保存好这些信息，然后启动长期服务：

sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs -f

测试本机访问：

curl -I http://127.0.0.1:7001

正常应返回：

HTTP/1.1 200 OK

5. 安装 Caddy

安装 Caddy：

sudo apt-get install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
  | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt-get update
sudo apt-get install -y caddy

写入 /etc/caddy/Caddyfile：

v.shishishi3.com {
	reverse_proxy 127.0.0.1:7001
}

474769754.xyz {
	handle /s/* {
		reverse_proxy 127.0.0.1:7001
	}

	handle /api/v1/client/subscribe* {
		reverse_proxy 127.0.0.1:7001
	}

	respond "Not Found" 404
}

解释：

v.shishishi3.com
完整反代 Xboard 面板。

474769754.xyz
只开放订阅路径，不暴露后台。

这里的 /s/* 很重要。Xboard 实际订阅链接可能是：

https://474769754.xyz/s/xxxxxxxxxxxxxxxx

排错

如果只放行 /api/v1/client/subscribe*，客户端导入订阅会被 Caddy 拦截。这种情况直接跳到订阅 404。

验证并重载 Caddy：

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo journalctl -u caddy -f

测试：

curl -I https://v.shishishi3.com
curl -I https://474769754.xyz

预期：

https://v.shishishi3.com -> 200
https://474769754.xyz -> 404

数字域名根路径返回 404 是正常的，因为我们故意不暴露面板。

排错

如果这里出现 unexpected eof while reading，跳到 Caddy TLS EOF。

6. Xboard 基础配置

进入后台后先改：

站点名称：xxx
站点 URL： 此处应为您的域名或子域名（例如 https://v.shishishi3.com）
订阅 URL：此处应为您的域名或子域名（例如 https://474769754.xyz）

安全建议：

后台路径：改成随机路径
开放注册：上线前再开（自用的话可以不开放）
邮箱验证：开启
登录验证码：开启
注册验证码：开启
订阅防盗：开启

如果只有一个 URL 字段，就填：

https://v.shishishi3.com

如果有单独订阅 URL，填：

https://474769754.xyz

7. 邮件 SMTP 配置（自用可以不用考虑此部分）

Cloudflare Email Routing 只能收信和转发，不能作为 SMTP 发信服务器。

推荐用 Brevo 免费 SMTP：

SMTP 主机：smtp-relay.brevo.com
SMTP 端口：587
加密方式：TLS
SMTP 用户名：Brevo 给你的 SMTP Login
SMTP 密码：Brevo SMTP Key
发件人地址：noreply@474769754.xyz

注意：

端口 587 对应 TLS/STARTTLS，不要选 SSL/TLS。
ac96b9001@smtp-brevo.com 这类地址是 SMTP 登录用户名，不是发件人地址。
发件人可以是 noreply@474769754.xyz，但必须在 Brevo 验证。
Cloudflare Email Routing 可以接收 Brevo 发给 noreply@474769754.xyz 的验证邮件。

Cloudflare DNS 里 SPF 只能有一条。如果 Cloudflare 已有：

v=spf1 include:_spf.mx.cloudflare.net ~all

Brevo 又要求：

v=spf1 include:spf.brevo.com ~all

要合并成：

v=spf1 include:_spf.mx.cloudflare.net include:spf.brevo.com ~all

如果发验证码收不到，先看 Xboard 日志：

cd /opt/Xboard
sudo docker compose logs --tail=160 xboard
sudo grep -R "SMTP\|Brevo\|SendEmailJob\|Unauthorized" storage/logs/

排错

如果日志里出现 525 5.7.1 Unauthorized IP address，直接跳到邮件验证码收不到。

8. 套餐设计

请根据您的实际节点机器和情况来，以下为我的套餐示例：

如果美国节点有较大流量，香港节点只有少量流量，建议这样定位：

美国圣何塞：主力节点，1x
香港节点：备用节点，5x / 8x / 10x

低价套餐示例：

套餐名：Vela Basic
月付：3.9 元
年付：36 元
流量：50GB/月
限速：300Mbps
设备数：3
US：1x
HK：5x 或更高

如果定价是：

月付：3 元
年付：30 元

建议：

流量：40GB/月
限速：200Mbps
设备数：2
HK：8x

套餐描述模板：

## 套餐详情

- 流量：{{transfer}} GB
- 速度限制：{{speed}} Mbps
- 同时在线设备：{{devices}} 台
- 主力节点：美国西岸圣何塞
- 备用节点：香港高倍率节点

## 服务说明

1. 流量{{reset_method}}重置
2. 支持多平台使用，适配常见 iOS、Android、Windows、macOS 客户端
3. 美国圣何塞节点为主力线路，万兆带宽接入，实际可用峰值约 1.8Gbps - 6Gbps
4. 香港节点为备用线路，因月流量有限采用高倍率计费，适合临时切换或低延迟访问
5. 适合日常浏览、社交媒体、AI 工具访问与轻度流媒体使用
6. 禁止 BT/PT、挖矿、扫描攻击、垃圾邮件及长时间占满带宽等滥用行为
7. 7×24小时技术支持

9. 创建 HY2 节点

在 Xboard 后台创建节点，类型选择：

Hysteria

示例 HK 节点：

节点名称：HK-HY2-01
基础倍率：5
流量限制：0
标签：HK, HY2
权限组：Default
节点地址：hk.474769754.xyz
连接端口：8443
服务端口：8443
协议版本：V2
混淆：开启
混淆实现：Salamander
混淆密码：随机生成
SNI：hk.474769754.xyz
允许不安全：关闭
ECH：关闭
上行带宽：按真实带宽填
下行带宽：按真实带宽填
绑定服务器：独立部署或绑定对应机器

示例 US 节点：

节点名称：US-HY2-01
基础倍率：1
节点地址：us.474769754.xyz
连接端口：8443
服务端口：8443
SNI：us.474769754.xyz

注意：

ECH 不是 TLS 证书，不要把 ECH 当成证书配置。
HY2 不走 Caddy 反代。
Caddy 不能用 reverse_proxy 代理普通 HY2 UDP 流量。
节点域名必须灰云。

下面这张图对应的是连接端口、服务端口、混淆、SNI 和 ECH 这些传输层相关配置：

如果你要配置端口跳跃和绑定服务器，可以参考下面这张对应界面：

10. 安装 Xboard-Node

您可以直接到 Xboard 的管理后台 -> 节点管理 -> 添加服务器获取安装 xboard-node 的相关代码，然后将命令在服务器中执行，等待下载完成即可。

在完成安装后可以看到面板的服务器显示在线以及负载等信息

11. HY2 证书配置

HY2 必须有 TLS 证书。

排错

如果你已经看到 protocol "hysteria" requires TLS certificate files，直接跳到服务器在线但节点未运行。

先申请证书。节点服务器上如果没有 Web 服务占用 80，可以直接：

sudo apt-get install -y certbot

sudo certbot certonly --standalone \
  -d hk.474769754.xyz \
  --agree-tos \
  -m admin@474769754.xyz \
  --non-interactive

如果同机有 Caddy 或 nginx 占用 80，先停服务，申请后再启动：

sudo systemctl stop caddy
sudo certbot certonly --standalone -d hk.474769754.xyz --agree-tos -m admin@474769754.xyz --non-interactive
sudo systemctl start caddy

证书路径：

/etc/letsencrypt/live/hk.474769754.xyz/fullchain.pem
/etc/letsencrypt/live/hk.474769754.xyz/privkey.pem

复制到 Xboard-Node 目录：

sudo mkdir -p /etc/xboard-node/certs

sudo install -m 0644 /etc/letsencrypt/live/hk.474769754.xyz/fullchain.pem \
  /etc/xboard-node/certs/hk.fullchain.pem

sudo install -m 0600 /etc/letsencrypt/live/hk.474769754.xyz/privkey.pem \
  /etc/xboard-node/certs/hk.privkey.pem

编辑配置：

sudo nano /etc/xboard-node/config.yml

顶层加入：

cert:
  cert_mode: file
  domain: hk.474769754.xyz
  cert_file: /etc/xboard-node/certs/hk.fullchain.pem
  key_file: /etc/xboard-node/certs/hk.privkey.pem

注意 cert: 必须是顶层配置，不要缩进到 panel: 或 machine: 下面。

重启：

sudo systemctl restart xboard-node
sudo journalctl -u xboard-node --since "2 minutes ago" --no-pager

验证 UDP 监听：

sudo ss -lunp | grep 8443

正常应该看到 8443/udp。

US 节点同理，把域名和文件名换成：

us.474769754.xyz
/etc/xboard-node/certs/us.fullchain.pem
/etc/xboard-node/certs/us.privkey.pem

12. 防火墙与安全组

面板服务器开放：

80/tcp
443/tcp
22/tcp

节点服务器开放：

8443/udp
22/tcp

如果使用端口跳跃：

20000-29999/udp

ufw 示例：

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 8443/udp
sudo ufw enable
sudo ufw status

如果云厂商有安全组，也必须放行对应 UDP。只开系统防火墙不够。

13. HY2 端口跳跃

Hysteria2 支持端口跳跃。推荐范围：

20000-29999/udp

Xboard 节点配置：

连接端口：20000-29999
服务端口：8443
Hop 间隔：30

节点服务器把端口范围转发到实际监听端口：

sudo iptables -t nat -A PREROUTING -p udp --dport 20000:29999 -j REDIRECT --to-ports 8443

保存规则：

sudo apt-get install -y iptables-persistent
sudo netfilter-persistent save

检查：

sudo iptables -t nat -S PREROUTING | grep 8443
sudo ss -lunp | grep 8443

稳定前建议同时保留：

8443/udp
20000-29999/udp

稳定后可以只保留端口跳跃范围。

排错

如果你担心 ss 看不到端口范围，跳到无法看到 UDP 端口范围。

14. 用户订阅与客户端

用户创建流程：

创建套餐 -> 创建用户 -> 给用户绑定套餐 -> 复制订阅链接 -> 客户端导入

如果客户端导入后只有 DIRECT，没有节点，常见原因：

用户没有有效套餐。
套餐权限组没有包含节点权限组。
节点隐藏开关开启了。
节点没运行。
客户端不支持 Hysteria2。
订阅模板不支持 HY2。

直接看订阅内容：

curl -L "https://474769754.xyz/s/你的token"

如果输出里没有：

hysteria
hy2
hk.474769754.xyz
US-HY2-01

说明 Xboard 没把节点发出来，优先查套餐和权限组。

如果输出里有节点，但客户端不显示，换支持 HY2 的客户端或换订阅类型，例如 sing-box、Clash Meta、Mihomo。

15. 开放注册前检查

建议上线前确认：

SMTP 测试邮件成功
邮箱验证开启
注册验证码开启
登录验证码开启
后台路径已改随机
订阅域名只放行 /s/*
套餐权限组配置正确
节点倍率配置正确
HK 节点倍率较高
云安全组只开放必要端口

试用策略建议：

注册送套餐：关闭
或 1GB / 1 天
低价套餐不要开放过多 HK 流量

16. 上线收口

最终建议端口：

面板服务器：

80/tcp
443/tcp
22/tcp

节点服务器：

22/tcp
20000-29999/udp

如果不用端口跳跃：

22/tcp
8443/udp

Caddy 只暴露：

面板域名完整反代
订阅域名只放行 /s/* 和必要 API

后台设置：

开放注册：按需开启
邮箱验证：开启
验证码：开启
后台路径：随机
试用额度：极低或关闭

节点策略：

US 主力，1x
HK 备用，5x / 8x / 10x

这样就能从测试态进入公开上线态。

注意事项

系统 apt 源报错

如果遇到这个错误：

E: The repository 'https://packagecloud.io/ookla/speedtest-cli/ubuntu noble Release' does not have a Release file.

说明 Ookla speedtest 的 apt 源不支持当前系统版本，先禁用它：

grep -R "packagecloud.io/ookla" /etc/apt/sources.list /etc/apt/sources.list.d/

假设输出是：

/etc/apt/sources.list.d/ookla_speedtest-cli.list

禁用：

sudo mv /etc/apt/sources.list.d/ookla_speedtest-cli.list \
  /etc/apt/sources.list.d/ookla_speedtest-cli.list.disabled

sudo apt-get update

这是我们实际踩过的坑。安装脚本里只要跑 apt-get update，这个坏源就会把整套流程卡住。

DNS 被 fake-ip 干扰

如果你本机开了代理或 TUN，可能会看到 198.18.x.x 这种 fake-ip。这时用公共 DNS 或临时关闭代理排查。

Caddy TLS EOF

现象：

curl: (35) TLS connect error: unexpected eof while reading

排查：

nslookup 域名 1.1.1.1
sudo caddy validate --config /etc/caddy/Caddyfile
sudo journalctl -u caddy -f

常见原因：

DNS 没指到服务器。
Caddyfile 没上传到服务器。
Caddy 没 reload。
80/443 没放行。

订阅 404

如果响应头是：

HTTP/2 404
server: Caddy
content-length: 9

说明 Caddy 拦了。确认 Caddyfile 放行：

handle /s/* {
	reverse_proxy 127.0.0.1:7001
}

邮件验证码收不到

看日志：

sudo grep -R "SendEmailJob\|SMTP\|Unauthorized" /opt/Xboard/storage/logs/

如果有：

525 5.7.1 Unauthorized IP address

这表示 Brevo 拒绝了发信出口 IP。查 Xboard 容器出口 IP：

cd /opt/Xboard
sudo docker compose exec -T xboard curl -s https://ifconfig.me

把返回的 IP 加到 Brevo 的 Authorized IP addresses 里。

服务器在线但节点未运行

看日志：

sudo journalctl -u xboard-node -n 120 --no-pager

如果有：

requires TLS certificate files

说明 HY2 缺证书配置，按第 11 节补 cert:。

节点运行但无人使用

这是正常状态，表示节点已经启动，只是当前没有客户端连接。

无法看到 UDP 端口范围

检查：

sudo ss -lunp | grep 8443

如果使用端口跳跃，ss 不显示 20000-29999 是正常的，因为程序实际监听的是 8443。要看 iptables：

sudo iptables -t nat -S PREROUTING | grep 20000

同时别忘了云厂商安全组也要放行 20000-29999/udp。

删除套餐失败

如果提示“该订阅下存在订单无法删除”，不要硬删。

参考资料

从磁盘到文件：用 macOS 理解 GPT、APFS、容器和卷

Sun, 21 Jun 2026 00:00:00 GMT

很多人第一次看 macOS 的磁盘结构时，都会被几个词绕住：磁盘、分区、容器、卷、文件系统、挂载点。它们看起来都像「硬盘的一部分」，但其实处在不同层级。

最容易混的地方在于，传统磁盘结构常常是「一个分区就是一个卷」，而现代 macOS 默认使用 APFS。APFS 在分区和卷之间又加了一层「容器」，一个容器里可以放多个卷，并且这些卷共享同一片空间。

所以这篇文章不从抽象定义开始，而是按 macOS 上最常见的路径往下看：

物理磁盘
  -> GPT 分区表
  -> 分区
  -> APFS 容器
  -> APFS 卷
  -> 文件和目录

如果是普通 exFAT 移动硬盘，结构通常更简单：

物理磁盘
  -> GPT / MBR 分区表
  -> 分区
  -> exFAT 文件系统卷
  -> 文件和目录

理解这两条线以后，磁盘工具里的 Macintosh HD、Macintosh HD - Data、Preboot、Recovery、VM，以及命令行里的 /dev/disk0、/dev/disk0s2、disk3，就不会再像一堆突然冒出来的设备。

物理磁盘：真正的存储设备

物理磁盘就是实际存在的存储设备，比如内置 SSD、外置硬盘、U 盘、SD 卡、NVMe 硬盘。

在 macOS 里，它可能显示为：

/dev/disk0
/dev/disk4

但要注意，disk0、disk4 这类编号不是永久身份。插拔设备、重启系统、挂载磁盘镜像后，编号都可能变化。判断当前磁盘结构时，更可靠的方式是直接看：

diskutil list

从底层看，物理磁盘本质上是一串连续的块。分区表负责说明：哪些块属于哪个分区。

GPT：磁盘上的分区地图

GPT 是现代 macOS 常见的分区表格式。它不管理文件，也不知道你的照片、文档、应用在哪里。它只记录磁盘被怎么切分。

GPT 通常记录这些信息：

分区从哪里开始。
分区到哪里结束。
分区类型是什么。
分区 GUID 是什么。
分区名称是什么。

所以 GPT 更像磁盘级别的地图。它告诉系统「这块地方是 EFI 分区，那块地方是 APFS 分区」，但不会进入分区内部管理文件。

老设备或某些兼容性场景里也会看到 MBR。对于现在的 Mac 系统盘和大多数现代外置盘，GPT 才是更常见的选择。

分区：磁盘上划出来的一段连续空间

分区是物理磁盘上的一段连续空间。

在 macOS 里，常见命名类似：

disk0      整块磁盘
disk0s1    第 1 个分区
disk0s2    第 2 个分区

一个分区里面可以放很多东西，比如：

APFS
HFS+
exFAT
FAT32
NTFS
Linux ext4
EFI System Partition

传统理解里经常是：

一个分区 = 一个文件系统 = 一个卷

比如一个普通 exFAT U 盘，大概率就是这样：

GPT 分区
  -> exFAT 文件系统
  -> 卷名 DATA
  -> 文件

这种情况下，分区和卷看起来几乎是同一个东西。但 APFS 不完全按这个直觉来。

文件系统：文件怎么被组织

文件系统负责定义文件如何存储、目录如何组织、权限如何记录、空闲空间如何管理。

常见文件系统包括：

文件系统	常见平台	特点
APFS	macOS、iOS、iPadOS	Apple 的现代文件系统，支持空间共享、快照、克隆、加密等
HFS+	老版本 macOS	APFS 之前的 Apple 文件系统
NTFS	Windows	Windows 系统盘常用
exFAT	跨平台	适合 U 盘、移动硬盘，兼容 macOS 和 Windows
FAT32	老设备	兼容性高，但单文件最大 4 GB
ext4	Linux	Linux 常用文件系统
Btrfs	Linux	支持快照、校验等现代特性
XFS	Linux	常见于大文件和服务器场景

文件系统会影响很多具体行为，比如文件名规则、文件大小上限、权限模型、是否支持快照、是否区分大小写、是否支持日志或写时复制。

macOS 当前最重要的文件系统是 APFS。它不只是「一种格式」，还带来了容器、空间共享、卷组、快照这些管理方式。

APFS 容器：共享空间池

APFS 的核心变化是「容器」。

一个 GPT 分区可以被用作 APFS 的物理存储空间，然后在里面创建一个 APFS 容器。这个容器再包含多个 APFS 卷。

典型结构像这样：

物理磁盘 disk0
  -> GPT 分区 disk0s2
    -> APFS Container disk3
      -> Macintosh HD
      -> Macintosh HD - Data
      -> Preboot
      -> Recovery
      -> VM

这里的 disk3 虽然也叫 disk，但它不是另一块物理硬盘，而是 macOS 合成出来的 APFS 容器设备。

APFS 容器最大的特点是：里面的卷可以共享空间。比如一个 1 TB 的 APFS 容器里有两个卷，卷 A 当前用了 200 GB，卷 B 当前用了 100 GB，那么剩下的空间不是预先固定给某个卷，而是仍然属于容器，可以按需分配给任意卷。

这和传统分区很不一样。传统分区如果提前切成两个 500 GB 分区，那么 A 分区用不完的空间，B 分区不能自动拿来用。APFS 容器则更灵活：多个卷共享容器里的空闲空间。

当然，APFS 卷也不是完全没有边界。需要手动控制时，可以给卷设置 reserve size 和 quota size：前者表示保底空间，后者表示最多能用多少空间。

卷：真正被挂载和使用的单位

卷是操作系统可以挂载、命名、显示，并让用户读写文件的逻辑单位。

在 Finder 里你看到的这些名字，通常都是卷：

Macintosh HD
Macintosh HD - Data
Backup
MyDisk

在命令行里，外置卷通常挂载到：

/Volumes/Backup

Windows 里的 C:、D: 也可以理解为卷。Linux 里常见的 /mnt/data、/media/xxx 则是卷被挂载后的访问位置。

所以「卷」强调的是操作系统层面的可用单位；「分区」强调的是磁盘上的连续空间；「APFS 容器」强调的是多个 APFS 卷共享的空间池。

挂载：把卷接入目录树

挂载就是把一个卷接入操作系统的目录树。一个外置硬盘卷名叫 Backup，在 macOS 中通常会挂载到：

/Volumes/Backup

没有挂载时，卷可能存在，文件系统也可能完好，但 Finder 里看不到，也无法通过正常路径访问里面的文件。

常见命令包括：

diskutil mount /dev/disk4s2
diskutil unmount /dev/disk4s2
diskutil unmountDisk /dev/disk4

其中 unmount 是卸载某个卷或分区，unmountDisk 是卸载整块磁盘上的所有可卸载卷。

Macintosh HD 和 Macintosh HD - Data 为什么分开

从 macOS Catalina 开始，Apple 把系统文件和用户数据拆开。大致可以理解为：

Macintosh HD          系统卷
Macintosh HD - Data   数据卷

系统卷存放 macOS 系统内容。现代 macOS 中，它是只读的；从 macOS Big Sur 开始，系统卷进一步成为 Signed System Volume，也就是签名系统卷。系统会验证系统内容是否被篡改，如果校验失败，启动过程会被阻止或要求重新安装系统。

数据卷则存放用户文件、应用数据、可写配置等内容。macOS 通过 APFS Volume Group 和 firmlink 等机制，把系统卷和数据卷在用户视角下组合成一个系统。

所以你在 Finder 里看起来像是在访问一个统一的磁盘，底下其实是两个职责不同的卷协同工作：

系统卷负责保持系统内容稳定、可验证。
数据卷负责保存用户和应用产生的可写数据。

这也是为什么不要简单地把 Macintosh HD - Data 当成「多出来的重复磁盘」。它是现代 macOS 文件管理体系的一部分。

APFS 卷组：把相关卷组合起来

APFS Volume Group 是一组有关联的 APFS 卷。

最典型的就是：

Macintosh HD
Macintosh HD - Data

它们组成系统卷组。这个设计让 macOS 可以同时做到两件事：

系统内容独立、只读、可验证。
用户数据保持可写，并继续出现在熟悉的目录位置。

用户平时看到的是一个整体，但系统内部知道哪些路径属于系统卷，哪些内容来自数据卷。

Preboot、Recovery、VM 是什么

APFS 系统容器里通常还会看到一些系统维护卷：

Preboot：保存启动 APFS 系统卷所需的信息。
Recovery：保存恢复环境，用于重装 macOS、磁盘工具、终端和系统恢复。
VM：保存虚拟内存、交换文件、休眠相关数据。
Update：部分 macOS 版本中可能出现，用于系统更新流程。

这些卷一般由系统自动维护，不建议手动删除。尤其是系统盘上的 Preboot 和 Recovery，看起来不常用，但真正出问题时可能就是救命入口。

格式化、抹掉、删除卷、删除分区不是一回事

磁盘工具里的几个操作名字很像，但层级不同。

格式化通常指在某个分区或卷上创建新的文件系统。例如：

diskutil eraseVolume ExFAT DATA /dev/disk4s2

这表示在 /dev/disk4s2 上创建 exFAT 文件系统，并把卷名设为 DATA。

抹掉磁盘则可能更彻底。如果你选中整块物理磁盘抹掉，macOS 可能会重建分区表、创建新分区、创建文件系统和卷：

diskutil eraseDisk ExFAT DATA GPT /dev/disk4

这会影响整块磁盘，原有分区都会消失。

删除 APFS 卷和删除 APFS 分区也不同。

删除 APFS 卷后，空间回到 APFS 容器内部：

APFS Container
  -> Volume B
  -> Free space inside container

删除 APFS 分区后，空间才回到 GPT 层面的未分配空间：

GPT
  -> EFI
  -> Free Space
  -> Other Partition

这就是很多人疑惑的地方：为什么我删了一个 APFS 卷，磁盘工具里没有出现真正的「未分配空间」？因为你只是删掉了容器内部的卷，而不是删掉 GPT 层面的分区。

快照：不是复制一整份文件

APFS 支持快照。快照记录的是某一时刻的文件系统状态，不是一开始就完整复制所有数据。

APFS 使用 Copy-on-Write。刚创建快照时，它占用的额外空间很少；之后文件发生变化，旧数据块被保留下来，快照才能继续看到旧状态。

这也是 Time Machine、系统更新回滚和系统恢复能够高效工作的基础之一。

不过快照也会占空间。如果你发现磁盘空间明明删了文件却没有马上回来，除了废纸篓、缓存、云同步之外，也可以检查是否有本地快照仍然保留了旧数据。

EFI 分区：别随便删的启动辅助区域

GPT 磁盘上常见一个 EFI System Partition，也叫 ESP。它通常使用 FAT32，用来保存 UEFI 启动相关文件。

macOS 外置盘有时也会创建 EFI 分区，即使它不一定真的用于启动。系统盘上的 EFI 分区不要随意删除。它平时安静得像不存在，但它属于启动链路的一部分。

RAID 和普通卷的关系

RAID 是把多个磁盘组合起来的技术。比如：

RAID 0：条带化，提高性能，没有冗余。
RAID 1：镜像，提高冗余。
RAID 5：带校验的冗余方案。
RAID 10：镜像加条带。

RAID 组合后，操作系统通常会看到一个新的逻辑磁盘。然后这个逻辑磁盘上仍然可以继续建立分区表、分区、文件系统和卷。

也就是说 RAID 不替代文件系统，它在更底层把多个物理磁盘组合成一个逻辑设备。

看到 diskutil 输出时怎么判断

在 macOS 中，快速判断可以看这些线索：

看到的内容	通常表示
`/dev/disk4`	整块磁盘，可能是物理磁盘，也可能是合成设备
`/dev/disk4s2`	某块磁盘上的第 2 个分区
`GUID_partition_scheme`	这块磁盘使用 GPT 分区表
`EFI`	EFI System Partition
`Apple_APFS`	这个分区被用作 APFS 物理存储
`APFS Container`	APFS 容器
`APFS Volume`	APFS 容器内部的卷
`Free Space`	GPT 层面的未分配空间

还有一个非常实用的命令：

diskutil apfs list

它会比 diskutil list 更清楚地展示 APFS 容器、卷、卷组、快照等信息。

总结

macOS 上最重要的结论是：

APFS 不是简单的“一个分区一个卷”。
它更像是在一个分区里建立容器，再由容器管理多个共享空间的卷。

理解这一点之后，再看磁盘工具里的 Macintosh HD、Macintosh HD - Data、Preboot、Recovery、VM，就不会觉得它们是凭空多出来的几块硬盘了。

参考资料

Linux 服务器部署 QQ 机器人：NapCat + NoneBot2 + GsCore + Caddy

Fri, 19 Jun 2026 00:00:00 GMT

这次我想在 Linux 服务器上把一套 QQ 机器人真正跑稳，于是最后落下来的方案是 NapCat + NoneBot2 + GsCore，前面再加一层 Caddy 做 HTTPS 和反向代理。思路并不复杂，但真正一路走下来，问题几乎都出在那些“看起来只是小细节”的地方：终端编码、脚手架命令、Web 后台监听地址、证书验证，甚至是最基础的 DNS。

这篇文章把整套过程整理成一份可以直接照着走的教程，也把我们这次遇到的坑和修法一并写下来。它不是“理想环境下一次成功”的笔记，而是更接近真实部署现场的版本。

最终架构

我们最终采用的是下面这条链路：

QQ / 群消息
  -> NapCat
  -> NoneBot2
  -> nonebot-plugin-genshinuid
  -> GsCore
  -> 具体业务插件（如 GenshinUID）

如果需要把后台安全地开放到公网，则再额外加一层：

Browser
  -> Caddy (HTTPS / reverse_proxy)
  -> NapCat WebUI / GsCore WebConsole

这里我有两个实际建议：

机器人消息链路和后台管理链路要分开理解。
6099 和 8765 不要直接裸露到公网，尽量只让 Caddy 回源到本机端口。

组件职责

NapCat：负责协议端和 QQ 登录，本质上是机器人和 QQ 之间的入口。
NoneBot2：负责 Bot 框架本身，接收 OneBot 事件、分发插件、组织逻辑。
GsCore：早柚核心，负责统一连接和插件生态。
nonebot-plugin-genshinuid：NoneBot2 侧连接 GsCore 的官方插件。
Caddy：负责自动 HTTPS、反向代理，以及把后台入口放到统一域名下。

环境准备

本文默认：

系统是 Ubuntu / Debian 系 Linux
你有 root 或 sudo 权限
服务器已经可以联网
你已经准备好一个用于登录的 QQ 账号
你有一个域名，并且后面会用 Cloudflare 管理 DNS

建议目录结构像这样：

~/qqbot        # NoneBot2 项目
~/gsuid_core   # GsCore 本体

第一步：安装 NapCat

NapCat 官方 Linux 安装器可以直接使用：

curl -o napcat.sh https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh
bash napcat.sh --tui

安装后，通常可以通过下面的命令再次进入它的 TUI：

sudo napcat

我们遇到的第一个坑：NapCat Shell 乱码

刚打开 Napcat Shell 时，我们看到的是一堆类似 ~@~A、~M~U 的乱码，而不是正常中文界面。这不是 NapCat 坏了，而是典型的终端字符集和 TERM 设置问题。

先检查：

locale
echo $LANG
echo $TERM

如果不是 UTF-8，可以先临时修正：

export LANG=zh_CN.UTF-8
export LC_ALL=zh_CN.UTF-8
export TERM=xterm-256color
sudo napcat

如果服务器没有对应 locale，再补：

sudo apt update
sudo apt install -y locales
sudo locale-gen zh_CN.UTF-8
sudo update-locale LANG=zh_CN.UTF-8

如果你不想使用中文 locale，用通用的 C.UTF-8 也可以：

export LANG=C.UTF-8
export LC_ALL=C.UTF-8
export TERM=xterm-256color
sudo napcat

登录 NapCat WebUI

NapCat 的 WebUI 默认通常在 6099 端口。启动后，可以在日志里看到带 token 的访问地址。登录后完成 QQ 扫码，并修改好 WebUI 密码。

第二步：创建 NoneBot2 项目

先建立 Python 虚拟环境：

mkdir -p ~/qqbot
cd ~/qqbot
python -m venv .venv --prompt nonebot2
source .venv/bin/activate

安装基础依赖：

pip install "nonebot2[fastapi]"
pip install nonebot-adapter-onebot

创建 .env：

HOST=127.0.0.1
PORT=8080
ONEBOT_ACCESS_TOKEN=改成你自己的长随机串
COMMAND_START=["/"]
COMMAND_SEP=["."]

创建 bot.py：

import nonebot
from nonebot.adapters.onebot.v11 import Adapter as OneBotV11Adapter

nonebot.init()

driver = nonebot.get_driver()
driver.register_adapter(OneBotV11Adapter)

if __name__ == "__main__":
    nonebot.run()

启动试一下：

source .venv/bin/activate
python bot.py

第三步：让 NapCat 连到 NoneBot2

在 NapCat 的网络配置里，新建一个 WebSocket 客户端，把它指向：

ws://127.0.0.1:8080/onebot/v11/ws

Token 要和 .env 中的 ONEBOT_ACCESS_TOKEN 保持一致。

如果出现 403，优先检查 token 是否一字不差。

第四步：安装 GsCore

根据 GsCore 官方文档，把它单独安装在 Bot 目录的同级：

cd ~
git clone https://github.com/Genshin-bots/gsuid_core.git --depth=1 --single-branch
cd gsuid_core

官方更推荐 uv：

uv python install 3.13
uv sync --python 3.13
uv run python -m ensurepip

启动 GsCore：

uv run core

首次启动后，会生成：

~/gsuid_core/data/config.json
~/gsuid_core/data/core_config.json

第五步：在 NoneBot2 里接入 GsCore

GsCore 在 NoneBot2 侧的官方插件是 nonebot-plugin-genshinuid。

我们遇到的第二个坑：`nb` 命令不存在

我们一开始按文档执行：

nb plugin install nonebot-plugin-genshinuid

结果报错：

-bash: nb: command not found

原因不是项目坏了，而是环境里没装 nb-cli。nb 不是 Python 自带命令，它是 NoneBot 的脚手架。

有两种解法：

解法 A：补齐 `nb-cli`

cd ~/qqbot
source .venv/bin/activate
pip install nb-cli
nb plugin install nonebot-plugin-genshinuid

解法 B：直接用 `pip`

如果你已经手写了 bot.py，其实直接安装插件通常就够了：

cd ~/qqbot
source .venv/bin/activate
pip install nonebot-plugin-genshinuid

这次我们更推荐第二种，因为路径更短，也更少引入额外依赖。

给 NoneBot `.env` 加上 GsCore 配置

在原有 .env 下面继续补：

gsuid_core_ws_token=123
gsuid_core_host=localhost
gsuid_core_port=8765
gsuid_core_botid=NoneBot2

配置 GsCore 的 `config.json`

编辑：

~/gsuid_core/data/config.json

至少确认这些值：

{
  "HOST": "localhost",
  "PORT": "8765",
  "masters": ["你的QQ号"],
  "WS_TOKEN": "123",
  "TRUSTED_IPS": ["127.0.0.1"]
}

注意：

WS_TOKEN 要和 NoneBot .env 里的 gsuid_core_ws_token 一致
masters 填你自己的 QQ 号，否则后面很多核心命令你没有权限执行

第六步：安装业务插件

GsCore 本体只能算平台，真正的功能还需要业务插件。

如果你已经把自己加入 masters，可以在聊天里让 GsCore 直接安装：

core安装插件GenshinUID

如果你更想手动装：

cd ~/gsuid_core/plugins
git clone -b v4 https://github.com/KimigaiiWuyi/GenshinUID.git --depth=1 --single-branch

安装完记得重启 GsCore。

第七步：访问 GsCore 后台

GsCore 的后台是它的 Web Console，默认路径是：

http://127.0.0.1:8765/app

如果你在本机浏览器访问，这通常就够了。

我们遇到的第三个坑：外网访问 GsCore 返回 502

我们在公网直接访问时拿到了 HTTP ERROR 502，后来看到 GsCore 的提示日志：

WebConsole挂载于本地, 如想外网访问请修改data/config.json中host为0.0.0.0!

这说明后台只监听本机，外部访问当然进不来。最直接的修法是把：

"HOST": "localhost"

改成：

"HOST": "0.0.0.0"

但更好的做法是不要直接把 8765 裸暴露出去，而是让 GsCore 继续只监听本机，再交给 Caddy 反向代理。

第八步：用 Caddy 暴露 NapCat 和 GsCore 后台

从实际安全性上看，把 6099 和 8765 直接开公网不是个好习惯。更稳妥的方式是：

NapCat WebUI 和 GsCore WebConsole 只监听本机
服务器只对外开放 80/443
由 Caddy 统一做 HTTPS 和反向代理

安装 Caddy

在 Ubuntu / Debian 上可以这样装：

sudo apt update
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy

第九步：我们遇到的第四个坑：Caddy 证书申请失败

Caddy 启动后本身是正常的，但日志里一直在报 challenge failed。最后发现问题并不在 Caddy，而是更前面的基础设施：我忘了去 Cloudflare 里添加 DNS 记录。

这类错误很典型，通常是下面几种之一：

域名没有正确解析到当前服务器
80/443 没有对公网放通
其他程序占用了 80 或 443
DNS 刚改完还没生效

排查命令

查看 Caddy 日志：

sudo journalctl -u caddy -n 80 --no-pager

检查域名解析：

dig +short napcat.你的域名 A
dig +short gscore.你的域名 A

检查监听情况：

ss -lntp | grep ':80\|:443'

检查防火墙：

sudo ufw status

如果你在 Cloudflare 里忘了加 DNS，那么 Caddy 的 ACME 验证当然不可能成功。这个问题很“基础”，但也最常见。

最终建议的安全姿势

如果只是自己使用后台，我建议这样收口：

6099 和 8765 不对公网开放
只开放 80/443
NapCat 和 GsCore 都只监听本机
用 Caddy 统一反代
后台本身保留 token / 强密码
如果条件允许，再加 IP 白名单或额外认证层

这里要特别提醒一点：邮箱不是认证机制。它只是 Caddy 申请证书时的联系邮箱，不是登录保护。真正保护你后台的，是 HTTPS、反代边界、后台密码、token，以及你有没有把源端口直接开到公网。

这次部署里最值得记住的四件事

1. TUI 乱码通常不是程序坏了，而是终端环境不对

先看 LANG、LC_ALL、TERM，别急着怀疑软件本身。

2. `nb` 命令不存在，往往只是没装 `nb-cli`

如果你走的是手写 bot.py 路线，很多时候直接 pip install 插件反而更省事。

3. 后台只绑定本地时，公网访问失败是正常现象

看到 host=localhost 或“挂载于本地”的提示，就不要继续往外网层面猜了。

4. HTTPS 证书失败，很多时候不是代理错了，而是 DNS 没配

反代、TLS、证书这些东西看起来高级，但最常见的故障点往往仍然是最基础的那层。

参考文档

结语

这套方案最后跑通时，我最强烈的感受并不是“终于把机器人装好了”，而是这类部署工作的难点从来都不只是安装命令本身。真正决定你后面省不省心的，是边界有没有收清楚：协议端和框架端是不是分离，后台是不是裸露在公网，域名是不是已经指对，日志是不是能帮你快速定位问题。

把这些边界收好之后，NapCat + NoneBot2 + GsCore + Caddy 其实是一套非常顺手的组合。它不算最轻，也不算最花哨，但足够清晰，足够稳定，也足够适合长期维护。

我的个人服务器框架重构

Tue, 16 Jun 2026 00:00:00 GMT

这次整理个人服务器，我最想解决的不是「再多跑几个服务」，而是把已经长出来的一堆服务重新放回清晰的边界里。

过去很多 HomeLab 的服务会自然堆在一起：博客、导航页、监控、面板、自研项目、机器人、Minecraft 私服，还有各种临时实验。它们一开始都只是「先跑起来」，时间久了之后，入口、域名、数据库、端口和备份策略就会互相缠在一起。出问题时很难判断是哪一层坏了，迁移时也很难只搬走其中一部分。

现在回头看，四月那版更像迁移草稿：先把 HK Main、Mac mini、代理节点和各个 Stack 的职责画出来。今天这版则更接近当前现场：哪些域名真的在用，哪些服务已经成为长期服务，哪些入口只是为了朋友访问或我自己维护而存在。

所以这套 framework 的目标很明确：公网入口统一，服务按职责拆分，敏感组件收回内网，静态内容尽量交给托管平台，真正需要长期运行、持久化或接入内网的服务再放到 Mac mini 上。

总体思路

当前架构采用「Cloudflare 统一 DNS/访问层 + HK Main 公网入口 + Mac mini 本地核心服务」的模式。

flowchart LR
    User["公网用户 / 朋友"] --> CF["Cloudflare DNS / CDN"]
    CF --> Pages["Cloudflare Pages<br/>Astro Blog 等静态内容"]
    CF --> HK["HK Main<br/>frps only"]
    HK --> FRPC["Mac mini<br/>frpc"]
    FRPC --> NPM["Nginx Proxy Manager"]

    NPM --> Monitor["monitor-stack<br/>Komari"]
    NPM --> Home["homepage-stack<br/>Homepage"]
    NPM --> Private["private-services-stack<br/>Nextcloud / Vault"]
    NPM --> VPN["vpn-stack<br/>VPN 下载与配置入口"]

    Friends["可信朋友"] --> GameAccess["Tailscale 优先<br/>frp / 域名备用"]
    GameAccess --> Games["game-stack<br/>Game Server"]

    VPN --> Nodes["代理 / VPN 节点<br/>按需接入"]

这里的关键是把「入口」和「业务」拆开。

HK Main 只作为公网入口，负责运行 frps，不承载数据库、不放个人文件、不跑长期业务，也不和代理出口节点混用。真正的服务运行在本地 Mac mini 的 Orbstack 里，由 frpc 接入 HK Main，再交给 Nginx Proxy Manager（NPM）做域名分流和反向代理。

静态博客仍然适合放在 Cloudflare Pages 这类托管平台上；但当前的 homepage.shishishi3.com 已经不是单纯的静态主页，而是 HomeLab 的导航和状态入口，所以它作为长期服务放在 Mac mini 上。这样一来，静态发布面和内网服务面不会互相拖累。

服务器角色

Mac mini 是这套系统的核心宿主机。它没有公网 IP，主要负责运行长期服务、数据库、自研项目、机器人和游戏服务。所有容器按 Docker Compose Stack 拆分，每个 Stack 都有自己的配置目录、数据目录和网络边界。

HK Main 是唯一暴露在公网入口层的主机。它只运行 frps，接收来自 Cloudflare 后的 HTTP/HTTPS 流量，再通过 frp 转发到 Mac mini。这个节点的职责越少越好，因为它在公网侧，攻击面必须尽量小。

代理或 VPN 节点只承担网络出口和接入职责，不参与 Nextcloud、Homepage、Komari、游戏服等主业务服务，也不和 HK Main 混用。节点可以增减，但入口层和本地服务层不跟着晃。

这种拆分的好处是边界清楚：入口坏了查 HK Main，业务坏了查 Mac mini，文件同步坏了查 Nextcloud，监控异常看 Komari，游戏访问异常查 gs 和对应端口，不需要在同一台机器上翻一堆彼此无关的容器。

域名规划

域名也按职责拆开。现在我不再把域名表写成「未来想跑什么」，而是直接按当前正在使用的入口来记。

shishishi3.com 用来承载面向我自己和可信访问者的常规 Web 服务：

子域名	服务	部署位置
`komari.shishishi3.com`	Komari 监控面板	`monitor-stack`
`homepage.shishishi3.com`	Homepage 导航与服务入口	`homepage-stack`
`vpndl.shishishi3.com`	VPN 下载、配置或说明入口	`vpn-stack`
`gs.shishishi3.com`	游戏服务访问入口	`game-stack`
`nc.shishishi3.com`	Nextcloud 文件与同步服务	`private-services-stack`
`v.shishishi3.com`	Vault / 私密工具入口	`private-services-stack`

这一版比四月的规划更收敛：status、panel、bot、demo 这些名字先从文章里拿掉，不再用它们代表当前状态。需要时当然还可以重新加，但域名规划应该反映正在跑的服务，而不是把所有可能性都提前占住。

基础设施域名则继续保持低调，只用来指向 HK Main、frp、节点或内部管理入口。普通服务入口放在 shishishi3.com 下，基础设施入口不要和业务域名混在一起。排查 DNS、证书、Cloudflare 规则和 NPM 反代时，这条线越清楚越省事。

公网入口

这套方案不把 Cloudflare Tunnel 作为主入口。Cloudflare 负责 DNS、CDN、WAF 和访问控制，真正需要回到本地的源站入口统一落到 HK Main。

Web 流量的路径大致是：

用户浏览器
  -> Cloudflare
  -> HK Main:80/443
  -> frps
  -> Mac mini frpc
  -> NPM
  -> Komari / Homepage / Nextcloud / Vault / VPN 入口等服务容器

端口转发采用 TCP 方式：

HK Main:80  -> frps:8080 -> Mac mini frpc -> NPM:80
HK Main:443 -> frps:8443 -> Mac mini frpc -> NPM:443

frps 只做转发，不在 HK Main 上处理业务请求。frpc 和 frps 之间启用 TLS 传输，NPM 负责域名分流、反向代理和证书管理。后端服务不直接向公网暴露端口，只加入 NPM 能访问到的 Docker 网络。

非 HTTP/HTTPS 服务不强行塞进 NPM。比如 gs.shishishi3.com 更像是游戏服务的友好入口标识，实际连接可以按游戏协议、端口和访问对象来决定：可信朋友优先走 Tailscale，无法安装客户端时再通过 frp 或受限端口作为备用入口。

Mac mini 上的 Stack 拆分

Mac mini 上的服务按职责拆成几层。名字不需要追求漂亮，关键是看到目录就能知道它负责什么。

edge-stack 是入口层，包含 frpc 和 NPM。它负责把公网流量接入本地，并把不同域名转发到对应服务。NPM 管理后台默认只允许内网或 Tailscale 访问，不直接暴露到公网。

monitor-stack 放 Komari。监控系统看起来只是一个面板，但它承担的是「我是不是该起来看一眼」这种责任，所以要独立持久化，升级时也不要和其他服务绑在一起。

homepage-stack 放 Homepage。它是人的入口，不是机器入口：链接、分组、服务状态、常用管理地址都可以放这里。它可以暴露给自己使用，但不应该顺手把每个后台都直接暴露出去。

private-services-stack 放 Nextcloud 和 v.shishishi3.com 这类私密服务。这里的共同点不是技术栈，而是数据敏感：文件、同步数据、密码库或其他私人资料都要有明确的数据卷、备份计划和访问限制。

vpn-stack 放 vpndl.shishishi3.com 对应的下载、配置或说明入口。它不一定需要复杂，但它牵涉到接入方式，所以要和普通展示项目分开，避免随手改一个页面时影响别人连接。

game-stack 放 gs.shishishi3.com 背后的游戏服务。游戏服务不和 Web 反向代理混用；访问上优先 Tailscale，备用方案才是 frp 或受限端口。存档、模组和配置文件单独持久化并定期备份。

临时项目仍然可以有自己的 projects-stack，但它不再是这篇文章里的主角。当前这套架构的核心不是「我能展示多少 demo」，而是 Komari、Homepage、VPN 入口、游戏服务、Nextcloud 和私密服务这些已经在使用的东西要稳定。

拆分以后，每个 Stack 都可以独立启动、停止、备份和迁移。新增服务时，先判断它属于哪一层，再加入对应 Stack，而不是把所有容器继续扔进同一个平面里。

安全策略

HK Main 的原则是「只做入口，不放业务」。它只开放 80、443、frps 控制端口和必要的高位转发端口；frps 使用强 Token，禁用默认管理端口；SSH 只允许密钥登录，禁止密码登录。

Mac mini 的原则是「服务分层，数据收口」。Orbstack 中按 Stack 拆分网络，数据库端口不映射到公网侧，NPM 管理后台不直接暴露公网，所有 .env、数据库密码、Token 和密钥文件都不提交到 Git。Nextcloud 和 Vault 这类服务尤其不能只满足于「页面能打开」，还要确认数据卷、备份和恢复路径。

Cloudflare 的原则是「域名分流，访问控制前置」。常规 Web 服务可以开启 CDN 和 WAF；面板类服务优先叠加 Cloudflare Access 或 IP 限制；证书尽量使用 DNS 验证或 Cloudflare Origin Certificate，避免 HTTP 验证被 frp 转发链路影响。

备份重点包括 Cloudflare Pages 项目配置、Astro Blog 源码仓库、Homepage 配置、Komari 数据、Nextcloud 数据和数据库、Vault 类服务的数据卷、VPN 配置入口、游戏存档和 NPM 配置。能恢复，才算真正部署完成。

维护顺序

现在这套东西已经不是单纯的迁移计划，所以后续维护也不应该从「启动所有容器」开始，而应该先把入口和数据边界理清楚。

第一步是盘点现有容器、镜像版本、端口映射、volume、数据库和配置文件，并完成一次可验证的备份。第二步在 Mac mini 上按 Stack 建立目录，每个 Stack 独立维护 compose.yml、.env 和 data/。

如果入口有变动，先检查 HK Main 的 frps、防火墙和必要端口，再验证 Mac mini 的 frpc 是否稳定连接。入口链路通了之后，再看 edge-stack 和 NPM，确认 npm-http、npm-https 转发注册成功，对应域名也命中了正确的 Proxy Host。

如果业务有变动，就按域名逐个验证：komari 看监控数据是否连续，homepage 看导航和状态卡片是否正确，vpndl 看下载和配置是否可用，gs 看游戏协议和端口是否通，nc 看文件同步和数据库状态，v 看登录、解锁和数据持久化。

最后检查 DNS、NPM 反代规则、备份任务和旧端口映射。确认新入口稳定后，再关闭旧容器或旧域名，不把所有风险堆到最后。

后续

这套 framework 现在已经从四月的「准备重构」进入了「按当前服务持续维护」阶段。后续还需要补齐几类具体模板：

monitor-stack 的 compose.yml 和 Komari 备份说明。
homepage-stack 的配置结构。
private-services-stack 的 Nextcloud / Vault 备份与恢复流程。
vpn-stack 的入口说明和访问控制清单。
game-stack 的 compose.yml。
NPM 反向代理规则清单。
定期备份脚本与恢复演练记录。

等这些模板补齐后，这套框架就不只是一次重构记录，而是一套可以反复复用的个人服务器部署方式：新服务按层加入，旧服务按层迁移，出了问题也能沿着入口、业务、数据和网络边界逐层定位。

在 codex 养宠物？真的假的？

Fri, 08 May 2026 00:00:00 GMT

本文整理了在 Codex 中启用 pet、安装自定义 pet、以及从一张参考图制作属于自己的 pet 的完整流程。示例以本仓库的 FleetSnowfluff 为准。

说明

适用场景：你已经在使用 Codex 桌面端或 Codex CLI，希望启用内置 pet，或者制作一个自己的动画 pet 并上传分享。

1. 先理解几个概念

1.1 Codex pet 是什么

Codex pet 是一个会随工作状态变化的小型动画伙伴。一个可安装的 pet 通常是一个本地文件夹，里面至少包含：

<pet-id>/
  pet.json
  spritesheet.webp

pet.json 负责描述名字、ID、说明和 spritesheet 文件路径；spritesheet.webp 是动画图集。

本仓库的最终安装包是：

~/.codex/pets/fleetsnowfluff/
  pet.json
  spritesheet.webp

1.2 `hatch-pet` skill 和 pet 包不是同一个东西

hatch-pet 是用于“制作 pet”的 Codex Skill。
~/.codex/pets/<pet-id>/ 是 Codex 最终读取的“pet 成品包”。

也就是说，别人给你一个已经做好的 pet 包时，你不需要安装 hatch-pet

只有自己从图片或 prompt 生成 pet 时才需要 hatch-pet

2. 如何在 Codex 中启用 pet

2.1 启用内置 pet

在 Codex 桌面端：

打开 Codex。
进入 Settings。
切到 Appearance。
找到 Pets 区域。
选择你想启用的 pet。
如果界面里有 Tuck Away Pet，可以用它暂时隐藏 pet。

也支持在 Codex 会话里使用：

/pet

如果你看不到 pet 选择器，先更新 Codex，再重启应用。

2.2 启用自定义 pet

把 pet 包放到本机 Codex pets 目录。

macOS / Linux：

mkdir -p "$HOME/.codex/pets/fleetsnowfluff"
cp pet.json spritesheet.webp "$HOME/.codex/pets/fleetsnowfluff/"

Windows PowerShell：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\pets\fleetsnowfluff"
Copy-Item .\pet.json, .\spritesheet.webp "$env:USERPROFILE\.codex\pets\fleetsnowfluff\"

然后重启 Codex，回到：

Settings -> Appearance -> Pets

选择 FleetSnowfluff。

3. 自定义 pet 的文件规范

3.1 最小 `pet.json`

{
  "id": "fleetsnowfluff",
  "displayName": "FleetSnowfluff",
  "description": "A tiny pink-haired chibi coder sprite with oversized sunglasses, white-blue outfit, and small attached wings.",
  "spritesheetPath": "spritesheet.webp"
}

注意：

id 建议使用小写字母、数字和连字符。
文件夹名最好和 id 一致。
displayName 是界面显示名，可以保留大小写。
spritesheetPath 通常指向同目录下的 spritesheet.webp。

3.2 spritesheet 图集规格

hatch-pet 工作流使用固定 atlas：

尺寸：1536 x 1872
网格：8 列 x 9 行
单格：192 x 208
格式：WebP 或 PNG，必须支持透明背景

9 行状态如下：

行	状态	帧数	用途
0	`idle`	6	待机、呼吸、眨眼
1	`running-right`	8	向右移动
2	`running-left`	8	向左移动
3	`waving`	4	挥手
4	`jumping`	5	跳跃
5	`failed`	8	失败或沮丧
6	`waiting`	6	等待
7	`running`	6	任务进行中
8	`review`	6	检查或 review

未使用的格子必须是透明的。

4. 如何制作一个属于自己的 pet：`hatch-pet`

如果你还没有安装 hatch-pet，在 Codex 中输入：

$skill-installer hatch-pet

安装后重启 Codex。

如果需要手动安装 curated skill，可以参考 OpenAI skills 仓库中的安装方式：

python "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo openai/skills \
  --path skills/.curated/hatch-pet

通常不需要自己手动跑这条命令，直接在 Codex 里用 $skill-installer hatch-pet 更方便。

5. 从参考图制作自己的 pet

5.1 准备参考图

参考图可以是：

角色头像
像素角色
吉祥物
截图
logo 或草图

图片越清楚，生成结果越稳定。最好提前决定：

pet 名字
要保留的核心特征
是否有必须保留的配件或身体结构
哪些东西不要生成

我们制作 FleetSnowfluff 时，参考图里最重要的特征是：

粉色短发
黑色大墨镜
白蓝色未来感服装
小型靴子
身体两侧的白蓝色翅膀

5.2 推荐 prompt 写法

可以这样要求 Codex：

使用 $hatch-pet，参考这张图片制作一个 Codex pet。
名字：FleetSnowfluff
必须保留：粉色短发、黑色墨镜、白蓝色衣服、白蓝色翅膀。
风格：Codex digital pet，像素感、小体型、粗轮廓、透明背景。
不要：文字、背景、阴影、漂浮装饰、音乐符号、散落星星。
完成后生成 pet.json、spritesheet.webp、QA contact sheet 和预览视频。

重点是把“必须保留”和“不要生成”写清楚。

5.3 正常生成流程

hatch-pet 的流程可以理解为 4 步：

准备 run 目录、名字、描述和 prompt。
生成 base pet，也就是主视觉参考。
基于 base 生成 9 行动作。
合成 spritesheet，做 QA，打包到 ~/.codex/pets/<pet-id>/。

我们当时的进度可以对应成：

Getting FleetSnowfluff ready.
Imagining FleetSnowfluff's main look.
Picturing FleetSnowfluff's poses.
Hatching FleetSnowfluff.

5.4 为什么要先确认 base

base 是后续所有动作行的身份锚点。base 错了，动作行通常也会错。

检查 base 时要看：

角色是不是完整全身。
核心特征是否保留。
是否有干净的纯色 chroma-key 背景。
是否有文字、阴影、漂浮装饰等不应出现的内容。
是否适合缩成 192x208 的小格子。

FleetSnowfluff 的第一次 base 没有翅膀，所以必须重做；第二次 base 保留了翅膀，才继续动作行生成。

6. 动作行生成要点

6.1 用子代理并行生成

hatch-pet 适合把动作行交给子代理并行生成。这样每个子代理只负责一个状态：

idle
running-right
running-left
waving
jumping
failed
waiting
running
review

父会话只负责：

记录生成结果
决定是否镜像 running-left
运行最终合成
检查 QA
打包 pet

这样可以避免多个代理同时改 imagegen-jobs.json 造成冲突。

6.2 不要随便镜像 `running-left`

有些 pet 可以用 running-right 水平镜像得到 running-left。但如果角色有非对称特征，就不要镜像。

FleetSnowfluff 有蓝色发夹、墨镜渐变和侧向翅膀细节，所以我们没有镜像，而是单独生成了 running-left。

判断标准：

有单侧发夹、徽标、文字、单边武器时，不镜像。
有方向性光照或手持道具时，不镜像。
左右完全对称的小动物，可以考虑镜像。

6.3 每行常见规则

idle：只做轻微呼吸、眨眼、上下浮动。
waving：只通过手部姿势表达挥手，不要画波浪线。
jumping：只用身体位置表达跳跃，不要画地面阴影或落地烟尘。
failed：可以有贴着身体的小眼泪或烟雾，但不要漂浮红叉、符号。
waiting：安静等待，不要新增复杂道具。
running：表示任务进行中，不是字面意义跑步。
review：用身体前倾、头部角度或手部姿态表达专注，不要加代码窗口或纸张。

7. QA 与验证

生成完成后，至少检查这些文件：

qa/contact-sheet.png
qa/reports/review.json
qa/reports/validation.json
qa/videos/*.mp4

本仓库的 QA 文件：

qa/contact-sheet.png
qa/reports/review.json
qa/reports/validation.json
qa/videos/

7.1 contact sheet 看什么

人工检查 contact sheet：

每一行状态是否正确。
每个状态的帧数是否正确。
角色身份是否一致。
翅膀、发型、墨镜、衣服是否保持一致。
有没有白底、阴影、漂浮杂物、裁切、空帧。

7.2 JSON 验证看什么

validation.json 应该没有：

"errors": []

最好也没有：

"warnings": []

review.json 应该显示每一行 ok: true。

7.3 预览视频

如果安装了 ffmpeg，可以生成每个状态的 mp4 预览。

如果 ffmpeg 不存在，spritesheet 和 pet 包仍然可以生成，只是没有视频预览。我们制作 FleetSnowfluff 时就先遇到了这个问题，安装 ffmpeg 后再补生成了：

qa/videos/idle.mp4
qa/videos/running-right.mp4
qa/videos/running-left.mp4
qa/videos/waving.mp4
qa/videos/jumping.mp4
qa/videos/failed.mp4
qa/videos/waiting.mp4
qa/videos/running.mp4
qa/videos/review.mp4

8. 重命名 pet 的正确方式

只改 displayName 不够。应该同步：

~/.codex/pets/<pet-id>/
pet.json
run metadata
README / docs
QA summary
Git 仓库目录

以 FleetSnowfluff 为例：

{
  "id": "fleetsnowfluff",
  "displayName": "FleetSnowfluff",
  "spritesheetPath": "spritesheet.webp"
}

同时目录应该是：

~/.codex/pets/fleetsnowfluff

如果你保留了生成 run 目录，也建议把旧名字全局替换，避免后续上传或二次维护时混乱。

检查残留名称：

rg -n "OldName|oldname" .

9. 打包成可上传仓库

建议最终仓库结构：

my-pet/
  README.md
  pet.json
  spritesheet.webp
  qa/
    contact-sheet.png
    reports/
      review.json
      validation.json
    videos/
      idle.mp4
      running-right.mp4
      running-left.mp4
      waving.mp4
      jumping.mp4
      failed.mp4
      waiting.mp4
      running.mp4
      review.mp4

初始化 git：

git init
git add .
git commit -m "Add FleetSnowfluff Codex pet"

上传到 GitHub：

git remote add origin git@github.com:<user>/<repo>.git
git push -u origin main

如果你用 HTTPS：

git remote add origin https://github.com/<user>/<repo>.git
git push -u origin main

10. 常见问题

pet 没出现在 Codex 里

检查：

是否放在 ~/.codex/pets/<pet-id>/。
是否有 pet.json 和 spritesheet.webp。
pet.json 里的 spritesheetPath 是否正确。
id 是否和目录名一致。
是否重启了 Codex。

pet 出现白底或背景残留

通常是透明背景处理失败。应重新生成或修复对应动作行，确保：

背景是纯 chroma-key 色。
不要阴影、渐变、光晕。
不要把背景色用在角色本体上。

某一行动作坏了

不要重做整只 pet。只修复失败行：

queue repair -> regenerate that row -> record result -> finalize again

动作中角色变样了

这是 identity drift。修复时要把 base、原图、contact sheet 和失败说明都作为 grounding context，要求只重做失败行。

想保留某个细节

必须在 base 生成前说明。比如 FleetSnowfluff 的翅膀就是必须保留项：

必须保留白蓝色翅膀；翅膀是身体轮廓的一部分，不是漂浮装饰。

11. 一份可直接复制的制作请求

使用 $hatch-pet 帮我制作一个 Codex pet。

名字：<YourPetName>
参考图：见附件
必须保留：
- <核心特征 1>
- <核心特征 2>
- <核心特征 3>

风格：
- Codex digital pet
- pixel-art-adjacent
- 小体型 chibi 比例
- 粗深色轮廓
- 透明背景
- 平面赛璐璐阴影

不要：
- 文字
- 背景
- 阴影
- 漂浮装饰
- 波浪线
- 速度线
- 粒子特效

请生成：
- pet.json
- spritesheet.webp
- QA contact sheet
- 每个状态的预览视频

如果某一步失败，只重试失败的行，不要重做整只 pet。
完成后整理为一个 git 仓库，方便上传。

12. 本仓库的 FleetSnowfluff 成品

pet.json
spritesheet.webp
qa/contact-sheet.png
qa/reports/review.json
qa/reports/validation.json
qa/videos/*.mp4

安装路径示例：

~/.codex/pets/fleetsnowfluff

当前仓库可直接上传，也可直接复制到 ~/.codex/pets/fleetsnowfluff 使用。

参考资料

外区 Apple ID 网页版注册教程

Wed, 06 May 2026 00:00:00 GMT

说明

注册和使用账号时，请遵守 Apple 服务条款以及当地法律法规，不建议购买、共享或使用来历不明的账号。

适用场景

这篇教程适合以下情况：

想下载 美区或其他地区 App Store 提供的应用；
需要体验 美区或其他地区 区域提供的 Apple 服务；
希望把主账号和外区账号分开使用，降低对 iCloud 主账号的影响。

不建议用于以下情况：

绕过版权、付费、订阅或地区法律限制；
使用虚假身份、虚假付款方式或无法确认来源的账单信息；
制作或购买第三方成品 Apple ID。

准备材料

开始前建议准备好：

一个没有注册过 Apple ID 的邮箱；
一个可以接收验证码的手机号（有外国手机号优先使用外国号，没有外国手机号时，+86 也可以，手机号可以重复注册多个账号）；
一台可以访问 Apple 官网的电脑、手机或平板；
稳定的网络环境（可不挂代理）；
后续如果要购买付费内容，再准备与 美区或其他地区 匹配的合法付款方式（国内优先考虑礼品卡）。

网页端创建 Apple Account 时，重点是邮箱、密码、国家或地区、生日和手机号验证。付款方式通常不是网页注册的核心步骤，后续登录 App Store、Apple Music、Apple TV 或 iCloud+ 等服务时，才可能被要求补充。

注册步骤

1. 打开 Apple 账号注册页面

在浏览器中打开：

https://account.apple.com/account

建议使用常用浏览器的无痕窗口或新浏览器配置文件，避免旧账号登录状态影响注册页面显示。

2. 填写账号信息

按页面提示填写：

项目	填写建议
姓名	随便填
国家或地区	选择 `[美区或其他地区]`
出生日期	只要大于 18 岁随便填
邮箱	使用未注册过 Apple ID 的邮箱
密码	建议使用强密码或自己熟悉的密码，并妥善保存
手机号	使用可以正常接收验证码的手机号

国家或地区是这一步的重点。这里选择的地区会影响后续 Apple 服务可见内容、付款方式、账单信息和部分年龄验证要求。

3. 选择是否订阅 Apple 更新

页面可能会提供 Apple 更新、新闻、软件、产品和服务相关邮件的订阅选项。

这一步不是必选项。想少收邮件可以取消勾选，想接收 Apple 官方信息可以保留勾选。

4. 完成验证码验证

点击继续后，Apple 通常会要求验证邮箱和手机号。

操作顺序一般是：

打开邮箱，查收 Apple 发送的验证码；
在网页中输入邮箱验证码；
查收短信验证码；
在网页中输入手机号验证码；
等待账号创建完成。

如果长时间收不到验证码，可以检查垃圾邮件、短信拦截、手机号格式、浏览器代理和网络状态。不要短时间内连续重复提交，以免触发额外限制。

5. 登录网页版 Apple Account

注册完成后，通常会自动登录到 Apple Account 页面。

登录后检查以下信息：

姓名和生日是否正确；
国家或地区是否为 美区或其他地区；
邮箱和手机号是否已验证；
账号安全设置是否完整；
双重认证是否已经开启或等待后续开启。

6. 后续补充付款与账单信息

由于外区绑定银行卡困难，建议选择「无 / None」的选项，然后使用礼品卡。

7. 登录到 App Store

注意

这一步虽然网页仍显示国家和地区，但是当登录 App Store 时可能会被送回国内区。所以，下一步是先切换 App Store 的地区。

这里使用的方法是地区切换链接。

首先退出 App Store 的账号。

iOS 26.4 及以上：打开 App Store，点击右上角的 Apple 账户头像，点击最上面的账号，验证后划到底部，点击「退出登录」。

iOS 26.3 及以前：打开 App Store，点击右上角的 Apple 账户头像，划到底部，点击「退出登录」。

macOS：打开 App Store，点击顶栏 Store 选项，然后退出登录。

重要

退出登录后请不要着急登录，否则账号可能会被送回原地区。

接下来把下面的链接直接复制粘贴到 Safari 回车。

地区	快捷跳转链接
美国	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143441&cc=us`
日本	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143462&cc=jp`
韩国	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143466&cc=kr`
香港	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143463&cc=hk`
尼日利亚	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143561&cc=ng`
土耳其	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143480&cc=tr`
埃及	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143516&cc=eg`
印度	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143467&cc=in`
阿根廷	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143505&cc=ar`

输入链接后出现无法连接 App Store 是正常的。

8. 检查账号

最后登录账号看下国家或地区对不对，并下载几个 App 锁定区域，避免被送回原地区，或者直接兑换礼品卡。

补充说明：因为 Apple 的转区策略要求账号不能有余额，所以直接兑换礼品卡可以比较稳定地锁区。

后续使用建议

外区 Apple ID 建议只用于 App Store 下载、更新和必要的区域服务，不建议替代主 iCloud 账号。

日常可以采用这种方式：

iCloud 保持登录主账号；
App Store 需要时切换到外区账号；
下载或更新完成后，再切回主账号。

这样可以减少照片、备份、通讯录和查找设备等核心数据受到影响的概率。

常见问题

为什么没有「None / 无」付款方式？

可能原因包括：

当前服务或当前地区不支持跳过付款方式；
账号首次使用媒体服务时需要补充账单信息；
付款方式、账单地址和账号地区不匹配；
设备、网络或账号状态触发了额外验证。

网页端注册不一定会立刻要求付款方式。后续使用 Apple 媒体服务或付费服务时，是否能选择「无」，最终以 Apple 页面显示为准。

外区 Apple ID 可以绑定国内银行卡吗？

不一定。Apple 支持的付款方式会因国家或地区变化。付款方式通常需要与账号所在国家或地区匹配，具体可查看 Apple 官方的付款方式支持列表。

可以长期和主账号混用吗？

可以，但建议只在 App Store 层面切换，不要频繁切换 iCloud 主账号。

需要注意的是，不同账号下载的应用通常需要使用对应账号更新。如果某个应用是用外区账号下载的，后续更新时可能需要再次登录这个外区账号。

账号被锁定怎么办？

优先使用 Apple 官方账号恢复入口：

https://iforgot.apple.com/

不要频繁尝试密码，也不要使用第三方解锁服务。

已经有 Apple ID，可以直接改地区吗？

可以在账号设置中修改国家或地区，但修改前通常需要处理订阅、余额、付款方式和家庭共享等问题。对主账号来说，直接改区的影响更大，所以更推荐使用单独账号管理外区 App Store 需求。

注意事项

开启双重认证；
保存好邮箱、手机号和恢复方式；
不要把账号借给别人使用；
不要购买成品账号；
不要在不可信设备上登录；
付款、订阅和家庭共享相关操作，以 Apple 官方页面提示为准。

关于礼品卡

闲鱼礼品卡最方便，但可能会面临黑卡或者汇率略高等问题。

对于美区，建议参考这篇文章：操作简单又安全靠谱的美区 Apple ID 礼品卡购买充值保姆级教程 - 知乎 Apple 大白

对于土区，建议直接去 SEAGM 或 Oyunfor，其中 SEAGM 支持支付宝，Oyunfor 仅支持 MasterCard、Visa 等银行卡。

参考资料

念念不忘，必有回响

Wed, 10 Jul 2024 00:00:00 GMT

All the past, all is overtrue.

人的一生总是在不断向前走，不断开始新生活。慢慢的，我们开始忘记了许多人、许多事…….

有人说，人生本来就是这样嘛，一辈子会遇到那么多的人，经历那么多的事，怎么可能全部记住啊。

对哦，怎么可能全部记住呢……

这里将会记录下我渐渐忘却的记忆，当我再次看见这些文字，希望我还可以回忆起已经丢失的记忆……

豕豕豕 - Blog

在 Mac 上原生玩《王国之泪》：MacNativeGames 构建与使用教程

1. 开始之前，先确认这些条件

机器与空间

游戏文件

2. 安装构建工具

可选：安装 Metal 工具链

3. 下载源码，整理文件

4. 选择一条构建命令

XCI 本体：先构建 1.0.0

NSP 本体：额外提供字体

本体加更新：以 1.4.3 为例

构建期间需要等多久

5. 第一次启动，先让它准备好

App 可以移动吗

6. 手柄与键盘操作

手柄：先留意确认键的位置

键盘：本文固定版本的布局

7. 画面设置，一次调整一项

8. 存档在哪里，更新前怎么备份

9. 常见问题

提示找不到 brew 或 python3.14

提示缺少 shared fonts

提示版本或哈希不匹配

双击后迟迟没有游戏窗口

一直卡顿，或者内存压力很大

有音效，但对白或背景音乐不正常

想安装 MOD

参考资料

在你的 Linux 服务器上部署 Xboard 实现自建机场

准备清单

架构图

正式教程

1. 服务器准备

2. DNS 配置

3. 安装 Docker 与 Compose

4. 部署 Xboard

5. 安装 Caddy

6. Xboard 基础配置

7. 邮件 SMTP 配置（自用可以不用考虑此部分）

8. 套餐设计

9. 创建 HY2 节点

10. 安装 Xboard-Node

11. HY2 证书配置

12. 防火墙与安全组

13. HY2 端口跳跃

14. 用户订阅与客户端

15. 开放注册前检查

16. 上线收口

注意事项

系统 apt 源报错

DNS 被 fake-ip 干扰

Caddy TLS EOF

订阅 404

邮件验证码收不到

服务器在线但节点未运行

节点运行但无人使用

无法看到 UDP 端口范围

删除套餐失败

参考资料

从磁盘到文件：用 macOS 理解 GPT、APFS、容器和卷

物理磁盘：真正的存储设备

GPT：磁盘上的分区地图

分区：磁盘上划出来的一段连续空间

文件系统：文件怎么被组织

APFS 容器：共享空间池

卷：真正被挂载和使用的单位

挂载：把卷接入目录树

Macintosh HD 和 Macintosh HD - Data 为什么分开

APFS 卷组：把相关卷组合起来

Preboot、Recovery、VM 是什么

格式化、抹掉、删除卷、删除分区不是一回事

快照：不是复制一整份文件

EFI 分区：别随便删的启动辅助区域

RAID 和普通卷的关系

看到 diskutil 输出时怎么判断

总结

参考资料

Linux 服务器部署 QQ 机器人：NapCat + NoneBot2 + GsCore + Caddy

最终架构

提示找不到 `brew` 或 `python3.14`

我们遇到的第二个坑：`nb` 命令不存在

解法 A：补齐 `nb-cli`

解法 B：直接用 `pip`

给 NoneBot `.env` 加上 GsCore 配置

配置 GsCore 的 `config.json`

2. `nb` 命令不存在，往往只是没装 `nb-cli`

1.2 `hatch-pet` skill 和 pet 包不是同一个东西

3.1 最小 `pet.json`

4. 如何制作一个属于自己的 pet：`hatch-pet`

6.2 不要随便镜像 `running-left`