我目前还在读博，这台开发服务器就放在实验室的桌面上，平时 24 小时开机。把开发环境集中在一台机器上之后，在宿舍、家里或者出差时，都能接着远程工作，不用每换一个地方就重新配置环境。

但实验室的供电并不总是那么省心，尤其是假期，经常遇到跳闸。电一断，远程连接也就没了，我还得想办法到实验室处理。这台联想来酷迷你主机又有一个让我头疼的问题：断电后重新开机会卡死。到现在还没确定是固件、硬件还是系统引导的问题，不能直接归因于 Debian；可以确定的是，我不能指望它每次恢复供电都能自己回到可访问状态。

所以这次给主机加了一台瓦力方程 W150 UPS。短时间停电时尽量维持运行，长时间停电时则希望给系统留出正常关机的机会。下面记录选购考虑、USB 状态读取、NUT 配置，以及接入过程中遇到的几个问题。

一、从迷你主机的取舍说起

最初选机器时，我也考虑过用手头的 DDR4 内存搭配旧平台准系统，尽量利用已有配件。后来选择这台成品机，很大程度上是受当时内存和整机价格影响，并不是觉得板载内存更适合开发服务器。这台机器的内存扩展空间有限，后面容器、开发服务和模型实验多起来，很难再靠加内存解决。若不是预算和配件价格的限制，我会更倾向于能更换、扩充内存的平台。

这些是当时购买时的取舍，不是现在的硬件购买推荐。继续使用已有机器后，供电和恢复能力也成了需要补上的部分。UPS 可以减少突然失电的机会，但不能修复主机断电后启动卡死的问题。

二、为什么选 W150，没有买 W180

UPS 也要放在实验室桌面上，我更看重体积、适合长期放置的电池方案，以及能否接入 Linux 监控。这次只考虑保护这台迷你主机，没有打算把整张桌面的设备都接进去，也没有为了更大的标称功率上 W180。

厂商的 W150 与 W180 对比页 列出，W150 使用磷酸铁锂（LiFePO4），W180 使用三元锂。这与 W150 在本次 USB 读取中上报的 battery.type: LiFePO4 一致。考虑到放在实验室桌面、长期接电，我更偏向磷酸铁锂的热稳定性，因此选择了 W150。这是我的选购权衡，并不代表三元锂产品不能使用，整机安全也不能只看电芯化学体系。

W150 属于面向直流设备的 UPS。实际接入前，要按机器和 UPS 的说明核对输入输出电压、接口极性、线材以及负载功率，不能只凭接口插得上、型号里带有某个数字就判断合适。功率决定能否带动负载，电池能量和实际负载才共同影响续航。

供电和监控是两条连接：

text
1
2
供电：市电 → 匹配的电源适配器 → W150 → 迷你主机监控：W150 → USB 数据线 → Debian 上的 NUT

USB 让系统知道 UPS 当前的状态，并不代替主机供电。UPS 也只保护接在其输出上的设备；上游网络设备如果同时失电，即使主机还在运行，也未必能继续远程访问。

三、让 Debian 先读到 UPS

3.1 安装与识别

本次记录的环境是 Debian 13，NUT 版本为 2.8.1。先安装所需组件：

bash
1
2
3
4
5
6
sudo apt updatesudo apt install nut-client nut-server usbutilslsusbupsc -Vsudo nut-scanner -U

当时的 USB 识别结果为：

text
1
ID 04d8:d005 Microchip Technology, Inc. Smart UPS W150

扫描结果推荐 usbhid-ups 驱动，随后实际读取也确认使用该驱动。不要只根据“UPS”这个设备类别就预先套驱动；同一个品牌的不同设备，也应以本机扫描和读取结果为准。usbhid-ups 文档

后续会修改 /etc/nut/ 中的配置。已有配置时，先备份：

bash
1
sudo cp -a /etc/nut "/etc/nut.backup-$(date +%Y%m%d-%H%M%S)"

下面列出关键有效项；编辑发行版已有配置时，修改对应项并保留相关默认设置，避免追加出重复定义。整个配置过程应在市电正常、可以处理主机状态的时段进行。

3.2 单机模式与驱动配置

这次由 UPS 通过 USB 直接连接主机，NUT 的服务端和监控端都运行在本机。/etc/nut/nut.conf 设置为：

conf
1
MODE=standalone

在 /etc/nut/ups.conf 中加入设备：

conf
1
2
3
4
5
6
[w150]    driver = usbhid-ups    port = auto    vendorid = 04d8    productid = d005    desc = "WalleCube W150"

w150 是本机配置中的逻辑名称，后面的查询、监控和服务实例都使用这个名称。只有一台对应设备时，这组标识已经能定位本次 UPS；多台同型号设备需要进一步区分，不能照搬为同一个实例。

/etc/nut/upsd.conf 只保留本机监听：

conf
1
2
LISTEN 127.0.0.1 3493LISTEN ::1 3493

无需为了本机监控把 NUT 端口开放给整个网络。随后启动驱动枚举和信息服务：

bash
1
2
3
4
5
6
7
sudo systemctl restart nut-driver-enumerator.servicesudo systemctl enable --now nut-server.servicesudo systemctl restart nut-server.servicesystemctl status nut-driver@w150.service --no-pagersystemctl status nut-server.service --no-pagerupsc w150@localhost

这里使用 Debian 13 的 systemd 驱动实例管理。其他版本若没有对应单元，应先检查发行版提供的服务方式，不要同时用手工驱动进程和 systemd 管理同一台 USB 设备。

3.3 当时遇到的两个错误

第一个是前台调试驱动时出现 USB Resource busy。检查后发现，nut-driver@w150.service 已经在运行，再启动一个 usbhid-ups 进程就会争用设备。因此，驱动服务正常时直接查询数据即可，无需再开第二个实例。

第二个是驱动已经运行，upsc 却返回 Connection refused。upsc 连接的是 upsd，不是直接读取 USB；启动 nut-server 后才打通了这段链路：

text
1
W150 → usbhid-ups → upsd → upsc

这两个问题分别发生在 USB 驱动层和本机服务层，检查顺序也应沿着这条链路进行。

四、实际读到了哪些状态

市电正常时，日志中的部分字段如下，设备序列号已省略：

text
1
2
3
4
5
6
7
8
battery.charge: 100battery.type: LiFePO4battery.runtime: 17354device.model: Smart UPS W150driver.name: usbhid-upsdriver.version: 2.8.1driver.version.data: openUPS HID 0.5ups.status: OL

在当时的断电识别检查中，又读到了：

text
1
2
input.current: 0.000ups.status: OB DISCHRG

OL 表示市电在线，OB 表示由电池供电，DISCHRG 表示正在放电。这次状态变化已经观察到，所以可以确认设备能够向 NUT 报告掉电。

不过 battery.runtime 是设备上报的估计值，不是我测出的续航。两次采样中它还出现了明显变化，不适合直接用来承诺运行时间。日志里的电压字段也有变化，读数的含义、不同供电状态下的输出和主机电压要求，都要结合设备说明核对；这里只把它们作为遥测，不能当作供电兼容性认证。

五、配置监控与半小时延迟策略

5.1 先接通 upsmon

upsmon 负责监视供电条件，并在达到关机条件时启动系统关机流程。先生成单独的监控密码：

bash
1
openssl rand -base64 24

将生成的值填入 /etc/nut/upsd.users：

conf
1
2
3
[upsmon]    password = your_random_password    upsmon primary

再修改 /etc/nut/upsmon.conf，两处密码保持一致：

conf
1
2
3
4
5
6
7
8
9
MONITOR w150@localhost 1 upsmon your_random_password primaryMINSUPPLIES 1SHUTDOWNCMD "/sbin/shutdown -h +0"POWERDOWNFLAG /etc/killpowerNOTIFYCMD /usr/sbin/upsschedNOTIFYFLAG ONLINE SYSLOG+EXECNOTIFYFLAG ONBATT SYSLOG+EXECNOTIFYFLAG LOWBATT SYSLOG+EXEC

这是单 UPS、单主机的配置。primary 让本机承担该 UPS 的主要监控角色，MINSUPPLIES 1 与唯一的供电来源相对应。配置文件包含监控密码，应限制读取权限：

bash
1
2
sudo chown root:nut /etc/nut/upsd.users /etc/nut/upsmon.confsudo chmod 640 /etc/nut/upsd.users /etc/nut/upsmon.conf

NOTIFYCMD 的路径需要按安装包核对。当时普通用户的 command -v upssched 没有输出，通过包文件列表才确认实际位置：

bash
1
dpkg -L nut-client nut-server | grep '/upssched$'

结果为 /usr/sbin/upssched。PATH 中找不到程序，不等于程序没有安装。

5.2 为什么增加计时器

我当时希望断电后留出半小时，给短时跳闸恢复供电留一点余量；超过这个时间，就进入关机流程。这个时间按自己的使用需求设置，实际部署时应结合负载和可用续航调整，给服务退出和文件系统写回留出余量。

计时策略为：

低电量本身也是 upsmon 的关键供电判断之一；下面的 LOWBATT 回调保留当时的配置，不能理解成“没有这个脚本，NUT 就不会处理低电量”。upsmon 配置说明

5.3 upssched 配置

/etc/nut/upssched.conf 的关键内容为：

conf
1
2
3
4
5
6
7
CMDSCRIPT /usr/bin/upssched-cmdPIPEFN /run/nut/upssched/upssched.pipeLOCKFN /run/nut/upssched/upssched.lockAT ONBATT w150@localhost START-TIMER onbatt_shutdown 1800AT ONLINE w150@localhost CANCEL-TIMER onbatt_shutdownAT LOWBATT w150@localhost EXECUTE lowbatt_shutdown

NOTIFYFLAG 中的 EXEC 不能漏掉，否则事件不会调用 NOTIFYCMD。START-TIMER 到期后把事件名传给处理脚本，CANCEL-TIMER 用于撤销仍在等待的计时器。upssched 配置说明

Debian 当时已经提供了专用运行目录：

text
1
2
3
/run/nut/upssched/owner: nut:nutmode: 0770

因此沿用这个目录存放管道和锁文件，没有把它们放进任何用户都能写的公共目录。/run 是运行期目录，重启后也需要由发行版的 tmpfiles/服务机制重建。

5.4 处理脚本与关机权限

当时修改的是 Debian 提供的 /usr/bin/upssched-cmd，其原始内容只有示例事件。下面保留本次使用的核心逻辑：

sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
#!/bin/shcase "$1" in    onbatt_shutdown)        logger -t upssched-cmd \            "UPS has been on battery for 30 minutes, requesting FSD"        /lib/nut/upsmon -c fsd        ;;    lowbatt_shutdown)        logger -t upssched-cmd \            "UPS battery is low, requesting FSD"        /lib/nut/upsmon -c fsd        ;;    *)        logger -t upssched-cmd "Unrecognized command: $1"        ;;esac

脚本使用实际安装的 /lib/nut/upsmon 路径，请先通过包文件列表核对。编辑已有脚本前也要备份；本次脚本设置为 root:root、0755，使监控用户可执行但不可修改：

bash
1
2
3
4
5
sudo cp -p /usr/bin/upssched-cmd "/usr/bin/upssched-cmd.backup-$(date +%Y%m%d-%H%M%S)"# 编辑完成后检查脚本语法和权限sh -n /usr/bin/upssched-cmdsudo chown root:root /usr/bin/upssched-cmdsudo chmod 755 /usr/bin/upssched-cmd

这是当时直接修改发行版脚本的记录。若重新整理部署，我会把自定义脚本放在 /etc/nut/upssched-cmd，同时修改 CMDSCRIPT，避免软件包升级覆盖自己的逻辑。

upsmon -c fsd 会请求真正的关机流程，不是无害的连通性测试。通知脚本通常在非特权监控用户下运行，最终的 SHUTDOWNCMD 才由有权限的部分执行。部署时要确保监控用户可执行处理脚本，并具备向运行中的 upsmon 发出控制请求所需的权限。upsmon 手册

5.5 启动监控

确认配置后启动监控：

bash
1
2
3
4
5
6
sudo systemctl restart nut-server.servicesudo systemctl enable --now nut-monitor.servicesudo systemctl restart nut-monitor.servicesystemctl status nut-monitor.service --no-pagersudo journalctl -u nut-monitor -n 50 --no-pager

当时的服务状态为 active (running)，日志也列出了 w150@localhost (primary)。监控进程至此已经加载目标 UPS，供电状态和事件处理也有了统一的日志入口。

六、计时与恢复供电的处理

这套配置通过 ONBATT 启动计时、ONLINE 取消计时，将短时停电和持续停电分开处理。ONLINE 只能取消仍在等待的计时器；一旦进入 FSD 关机流程，来电事件不会撤回关机。计时依赖正在运行的调度进程，也不应当作跨重启保存的停电时钟。upssched 手册

UPS 缓冲供电与主机恢复开机也有不同的条件。主机正常关机后，如果 UPS 一直维持输出，市电恢复时主板未必经历一次新的供电恢复事件。因此，BIOS 中的恢复供电自动启动选项，需要结合 UPS 的输出行为理解。

本次采用的是由 NUT 监视供电状态、按时间或低电量条件请求系统关机的配置。对于放在实验室长期运行的开发主机，这让突然失电之前多了一段缓冲时间，也把供电状态纳入了 Debian 的服务管理和日志中。

参考

• 瓦力方程 W150 与 W180 产品对比
• NUT usbhid-ups 驱动
• Debian trixie 的 upsmon 手册
• NUT upsmon.conf 配置
• NUT upssched.conf 配置
• Debian trixie 的 upssched 手册

在 Debian 上配置好开发环境和桌面工具后，为了正常访问 GitHub 等外部服务，我又通过 Clash 给日常使用的程序配置了代理。平时习惯把这个需求叫作“全局代理”，希望开着代理工作时，不用再为每个命令单独切换网络。

随后却遇到了另一个问题：Obsidian、Zotero 使用的内网服务突然访问不顺了。这些服务通过域名访问，在内网 DNS 中解析到局域网地址。原本以为已经把内网网段写进了代理排除列表，就不会受到影响，实际请求却还是进了代理。

同一段时间，ChatGPT 桌面端也出现了启动白屏。从终端指定代理后能很快打开，直接点击桌面图标却不行。这两件事刚好把代理配置的两头都碰了一遍：内网服务需要绕过代理，外部服务又需要让桌面启动器明确带上代理参数。

本文接着 Homelab 搭建手记（5）Obsidian 与 Zotero Linux 部署 记录这次调整。下面的域名和内网地址均已替换为示例；排障日志以 WebDAV 为例，不涉及修改笔记库、文献库或服务端数据。

一、先看请求到底发到了哪里

1.1 DNS 能解析，不代表请求会直连

假设内网 WebDAV 使用 webdav.home.example.com，本机解析结果为 192.168.50.10。当时代理排除列表的关键问题是只有回环名称和 IP 网段，缺少访问时使用的域名：

bash
1
2
export https_proxy=http://127.0.0.1:7890export NO_PROXY="localhost,192.168.0.0/16"

我先对同一个地址做了两次请求：

bash
1
2
3
4
5
6
7
8
# 替换为自己的内网服务域名getent ahosts webdav.home.example.com# 按当前终端代理配置访问curl -Iv --connect-timeout 10 https://webdav.home.example.com# 本次请求明确绕过 curl 的代理配置curl --noproxy '*' -Iv --connect-timeout 10 https://webdav.home.example.com

第一次请求的关键日志如下，域名已脱敏，省略了证书细节：

text
1
2
3
4
5
6
* Uses proxy env variable https_proxy == 'http://127.0.0.1:7890'*   Trying 127.0.0.1:7890...> CONNECT webdav.home.example.com:443 HTTP/1.1< HTTP/1.1 200 Connection established...< HTTP/2 401

加上 --noproxy '*' 后，连接对象变成了内网服务：

text
1
2
3
4
5
* Host webdav.home.example.com:443 was resolved.* IPv4: 192.168.50.10*   Trying 192.168.50.10:443......< HTTP/2 401

这组结果能确认：默认请求进入了本地 HTTP 代理，强制直连时则使用了本机解析得到的内网地址。两次请求都收到了 401，不能把第一条日志写成“代理连接失败”，也不能据此判断 DNS 已经损坏。

这里没有提供 WebDAV 账号密码，401 是服务要求认证的响应。它说明请求到达了某个要求认证的 HTTP 服务；是否为预期服务，还要结合证书和服务端信息确认。它也不代表 WebDAV 的目录访问、上传和同步已经通过验证。

1.2 网段排除没有覆盖域名访问

我原先把“域名解析到内网 IP”和“命中代理绕过规则”当成了一件事。但这次请求使用的是 webdav.home.example.com，排除列表里写的却是 192.168.0.0/16。

NO_PROXY 的匹配细节取决于客户端。不能假定程序都会先解析域名，再拿结果匹配其中的网段。对于这里的 curl 请求，已有日志已经说明网段规则没有实现预期的域名绕过，因此应直接把内网域名加入列表。

curl 支持逗号分隔的排除项，.home.example.com 这样的后缀可用于匹配该域下的主机；CIDR 网段写法从 curl 7.86.0 开始支持。其他应用是否支持相同语法，需要分别确认，不能把 curl 的配置当成所有桌面程序的统一标准。curl 代理环境变量说明

二、补全内网域名的代理绕过配置

2.1 调整终端中的代理变量

我的代理配置放在 ~/.bashrc.d/proxy.sh。这是自己组织 Bash 配置时使用的文件，Bash 不会自动扫描这个目录，仍需由 ~/.bashrc 加载。

编辑前先备份已有文件，再把代理变量整理为下面这样：

bash
1
2
# 已有配置时先保留副本cp -p ~/.bashrc.d/proxy.sh ~/.bashrc.d/proxy.sh.bak-$(date +%Y%m%d-%H%M%S)

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# ~/.bashrc.d/proxy.sh# 端口按本机代理软件实际监听情况填写export http_proxy="http://127.0.0.1:7890"export https_proxy="$http_proxy"export HTTP_PROXY="$http_proxy"export HTTPS_PROXY="$https_proxy"# 仅当该端口也提供 SOCKS5 服务时使用export all_proxy="socks5://127.0.0.1:7890"export ALL_PROXY="$all_proxy"# 示例内网域名和网段，请自行替换export no_proxy="localhost,127.0.0.1,::1,.home.example.com,192.168.0.0/16"export NO_PROXY="$no_proxy"

这里真正新增的是内网域名后缀，并让大小写两份排除列表保持一致。只应加入确定需要直连的范围；如果自己的主域名同时承载公网和内网服务，使用专门的内网子域或精确主机名，避免把公网服务也一并排除。

HTTP 和 SOCKS5 是否共用 7890，取决于代理软件的监听配置。数字相同不代表协议一定都可用。https_proxy 写成 http://127.0.0.1:7890，表示连接的是 HTTP 代理，访问 HTTPS 目标时可通过 CONNECT 建立隧道，不是把目标网站降级成 HTTP。

保留小写 http_proxy 很有必要：curl 不接受大写 HTTP_PROXY 作为 HTTP 代理变量。协议专用变量又优先于 ALL_PROXY，因此本例 HTTPS 请求首先使用 https_proxy。curl 代理环境变量说明

2.2 加载配置并验证访问路径

如果还没有加载入口，可以在 ~/.bashrc 中加入一次：

bash
1
2
3
if [ -f "$HOME/.bashrc.d/proxy.sh" ]; then    . "$HOME/.bashrc.d/proxy.sh"fi

当前终端直接加载后，再运行不带强制绕过参数的请求：

bash
1
2
. ~/.bashrc.d/proxy.shcurl -Iv --connect-timeout 10 https://webdav.home.example.com

这时要看连接目标是否变成内网 IP，以及是否还出现连接本地代理的 CONNECT 请求。再选一个确实需要代理的外部站点检查，确认没有把所有请求都改成直连：

bash
1
curl -Iv --connect-timeout 10 https://github.com

当时补上域名排除项后，内网访问问题得到了解决。不过终端测试只覆盖当前 shell；回到 Obsidian 和 Zotero，还要分别执行同步检查。可以用一个临时笔记或测试附件确认读写结果，不能只凭 curl 收到 HTTP 响应就认定应用同步正常。

三、终端配置与桌面程序之间还有一层

从 XFCE 菜单启动应用，通常不会经过交互式 Bash。刚刚在终端执行的 source，也不会更新已经运行的桌面程序。

遇到“curl 已经直连，应用仍然失败”的情况，我会继续检查应用的启动方式、继承环境以及自身代理设置。Obsidian 的同步插件可能使用不同的请求实现，Zotero 也有自己的网络配置，不能因为它们在同一个桌面里运行就假定行为相同。

如需检查进程环境，先找到并人工确认主进程 PID，再仅筛选代理相关变量：

bash
1
2
3
4
pgrep -af 'obsidian|zotero'# 用实际确认的 PID 替换 12345tr '\0' '\n' < /proc/12345/environ | grep -iE '^(http_proxy|https_proxy|all_proxy|no_proxy)='

这些变量能帮助判断启动时继承了什么，但不能证明应用一定采用它们。输出也可能带有代理认证信息，排障时不要直接贴出未经检查的完整环境。

另外，“全局代理”这个叫法需要拆开理解：环境变量只影响采用它们的程序；桌面系统代理是否生效取决于应用；TUN 则可能在路由层接管流量。curl --noproxy '*' 只能取消 curl 自己使用的显式代理，不能绕过系统中的 TUN。

如果使用 TUN 或代理内核统一接管流量，就要在对应配置中同时检查内网直连和 DNS 策略；代理客户端真正处于 Global 模式时，也不能默认普通分流规则会执行。本次记录中的直接修复是补全环境变量排除项，没有把代理内核切换模式当成已经完成的操作。

四、ChatGPT 桌面端白屏与 .desktop 启动参数

4.1 先在终端确认代理参数有效

ChatGPT 桌面端的表现刚好相反：点击图标停在启动白屏，用下面的命令却能很快打开：

bash
1
chatgpt --proxy-server="socks5://127.0.0.1:7890"

这里记录的是我在 Debian + XFCE 环境中安装、命令名为 chatgpt 的客户端。这个结果说明显式指定代理改善了该次启动的网络访问，但单凭这一点，还不能断言白屏一定由环境变量缺失导致，更不能推广成所有平台、所有客户端版本的通用处理。

--proxy-server 是 Electron 提供的代理参数之一；具体安装包是否接受或透传参数仍需实测。本例已经有终端启动成功的对照，接下来把同样的参数放进桌面入口即可。Electron 启动参数文档

4.2 修改用户级启动器

先找当前应用的 .desktop 文件。常见位置是 ~/.local/share/applications/、/usr/local/share/applications/ 和 /usr/share/applications/，文件名不一定就是 chatgpt.desktop：

bash
1
2
find ~/.local/share/applications /usr/local/share/applications /usr/share/applications \  -iname '*chatgpt*.desktop' 2>/dev/null

如果已经存在用户级文件，先备份再编辑它。如果只有系统级文件，可以复制到用户级目录，保留同名入口。下面以 chatgpt.desktop 为例，实际路径以查找结果为准：

bash
1
2
3
4
5
6
7
8
mkdir -p ~/.local/share/applications# -i 会在目标已存在时询问，避免覆盖原有用户配置cp -i /usr/share/applications/chatgpt.desktop ~/.local/share/applications/chatgpt.desktopcp -p ~/.local/share/applications/chatgpt.desktop \  ~/.local/share/applications/chatgpt.desktop.bak-$(date +%Y%m%d-%H%M%S)nano ~/.local/share/applications/chatgpt.desktop

在主 [Desktop Entry] 段中，原先的启动命令是：

ini
1
Exec=chatgpt %U

修改为：

ini
1
Exec=chatgpt --proxy-server="socks5://127.0.0.1:7890" %U

这也是我目前启动器里保留的配置。其他字段和原有参数沿用安装包提供的内容，不需要重新手写整份 MimeType 列表。

%U 表示启动器传入的 URL 列表，每个 URL 作为独立参数传给应用，因此要保留为单独一项。chatgpt 没写绝对路径时，启动器使用桌面环境的 PATH 查找它；如果原文件已经使用绝对路径，就保留原路径。Desktop Entry 的 Exec 规范

这里的 Exec 也不是普通 shell 脚本。不要直接在其中拼接 source ~/.bashrc && ...。若启动器对引号解析有差异，上面不含空格的代理地址也可写成 --proxy-server=socks5://127.0.0.1:7890，%U 仍单独保留。

4.3 从实际使用的图标重新验证

保存后，先从应用菜单正常退出 ChatGPT，再点击菜单图标重新打开。只关闭窗口时应用可能仍留在后台，新一次启动也可能复用旧进程，导致改过的参数没有真正用于启动主进程。

如果终端有效、图标仍白屏，继续检查：

• 点击的是应用菜单入口，还是桌面上另存的一份 .desktop 文件？后者需要检查自己的 Exec。
• 面板固定的启动器是否保存了旧命令？必要时重新固定正确的菜单项。
• SOCKS5 监听是否已启动，端口是否与配置一致？
• 用户级覆盖文件是否仍保留旧版本启动参数？应用升级后应与新的系统入口比较。

update-desktop-database 主要更新 MIME 关联缓存，不能把它当成所有菜单和面板启动器的强制刷新命令。修改后应以实际点击结果为准。

如果需要撤销这次调整，恢复备份中的 Exec 即可。用户级覆盖文件也应持续维护，避免安装包更新了系统启动器，而自己的旧副本一直遮住新配置。

五、保留下来的配置边界

这次调整之后，我保留了两处明确配置：内网服务域名进入 NO_PROXY/no_proxy，ChatGPT 桌面入口带上已经在终端验证有效的代理参数。

以后再遇到类似问题，可以沿用同一组检查：内网域名解析是否符合预期、请求实际连接的是服务还是代理、应用同步是否可用，以及退出后从菜单启动是否仍然正常。这样既能保留访问外部服务所需的代理，也能让内网服务按预期直连。

参考

• curl 代理环境变量
• Electron 支持的启动参数
• Desktop Entry：Exec 参数与字段代码

前面几篇已经介绍了主题的目录、搜索、评论和文章加密等功能。最近继续调整页面时，发现各个组件的颜色和边框不太统一，日间模式还有一些配色没有处理好，侧边栏和页脚在窄屏、短窗口下也有布局问题。

所以这次把相关样式和脚本一起整理了一遍。背景仍然保留星空，补充日间配色和日月切换，同时调整文章的滚动区域。本文记录具体改法，以及布局调整中遇到的几个问题。

一、整理配色配置

1.1 减少重复的颜色配置

旧主题把背景、正文卡片、侧边栏、按钮、代码块、边框和阴影都暴露为单独的配置项。开始看上去很灵活，但实际维护时有两个问题。

修改夜间背景时，还要同步调整侧栏、卡片和按钮；新增搜索弹窗或评论组件时，又容易漏掉日间颜色。各处单独配置，也容易出现文字和背景对比度不够、相似按钮颜色不同的问题。

这次减少了对外配置项，保留外观模式、两种强调色、基础字号、正文宽度和侧栏宽度。旧版逐组件设置颜色的配置需要随之调整。

yaml
1
2
3
4
5
6
7
8
9
style:  appearance: night # night | day | system  accent: "#E7A63A"  accent_secondary: "#73C4F5"  typography:    font_size: "16px"  layout:    content_width: "46rem"    sidebar_width: "18rem"

其余颜色在主题内部通过 CSS 变量管理，按背景、正文、边框等用途区分。卡片、侧栏、搜索框引用对应变量，修改配色时就不用逐个查找组件样式。主要变量如下：

text
1
2
3
4
5
6
7
8
--dt-canvas             页面天空与底色--dt-surface            文章等主要表面--dt-chrome             顶栏、侧栏、页脚的低对比度表面--dt-control            卡片内的次级按钮或 chip--dt-text / muted       正文与弱文字--dt-border             共享边界--dt-accent             当前状态和主操作--dt-accent-secondary   链接与辅助定位

切换昼夜模式时，统一修改这些变量的取值，搜索、目录、评论、代码块和静态页面便能一起切换配色。

1.2 日间配色与日月切换

主题默认使用夜间模式，背景为深靛蓝，保留星光和流星，按钮与链接使用金色、冷蓝色。日间模式改用偏暖的浅色背景，加入日晕和云层光尘，并调整文字、卡片和边框颜色。

外观策略支持 night、day 和 system。前两者固定初始状态，system 读取浏览器的 prefers-color-scheme。页头的圆形日月按钮只保存浏览器本地偏好，不回写主题 YAML；这样站点默认策略和访问者个人选择可以共存。

日月本身也不再是两个始终并列的图标。背景中使用一个超出屏幕的轨道作为旋转面，切换时月亮沿轨道下沉、太阳从另一侧进入；按钮则只保留当前可见的一个符号。日间画布补充缓慢移动的云层和日晕，夜间保留星空与流星。持续动画在页面不可见、用户启用减少动效或屏幕过窄时会降低或停止，避免把装饰变成阅读负担。

二、整理模板与浏览器脚本

2.1 Pug 只描述页面结构

这一轮曾暴露出一个很典型的问题：页面模板一边负责输出 HTML，一边绑定点击事件、拼接小段脚本。短期很快，长期会让行为散落在搜索、文章、侧栏和静态页面中，难以测试，也很难判断某次样式调整是否改坏了交互。

因此模板只保留语义结构、可访问性属性和模块所需的数据属性。例如搜索区域作为页面根层的 dialog 输出，而不是被锁在 header 内；目录/站点概览切换按钮只提供当前标签和状态；加密文章只输出密码表单与错误区域。事件绑定、焦点管理和状态同步都交给浏览器模块。

搜索、外链和加密功能分别做了以下调整：

1. 搜索对话框可以在全屏遮罩上居中，打开时隔离背景焦点，按 Escape 关闭，并把焦点还给触发按钮。
2. 外链跳转拦截可以在全局注入脚本中一次处理，而不是在每篇文章生成时改写链接或重复绑定监听器。这样不会把正常外链在构建期改成重定向地址，避免影响文章的原始链接和 SEO。
3. 二维码和文章解密等行为可以独立加载。模板不再内嵌密钥相关的运行时逻辑，错误提示也使用页面内的 role="alert"，而不是浏览器原生弹窗。

2.2 浏览器代码按职责拆分

浏览器端仍以 main.js 为入口，但入口只负责初始化。背景、外观、header、侧栏、二维码、加密、对话框和外链处理分别位于对应模块中；通用的焦点隔离和对话框生命周期归入 utils/。

text
1
2
3
4
source/js/├── layout/       # 背景、外观、顶栏、侧栏等页面骨架├── features/     # 二维码、加密等可选能力└── utils/        # dialog、外链拦截、滚动等通用行为

调整后，页面结构在 Pug 中修改，颜色和布局在 CSS 中修改，事件绑定在浏览器 JS 中处理。Hexo 的过滤器和 injector 负责构建时的生成与注入，排查问题时也可以按这几处分别查找。

三、重新组织页面骨架

3.1 让页脚固定，文章独立滚动

传统文档流中，页脚会跟随文章内容向下移动。对长文来说没有问题，但在这个主题里，顶栏、侧栏、阅读进度和回到顶部都已经是页面框架的一部分；继续让整个 body 滚动，容易造成组件各自监听不同滚动源。

这里把主容器高度设为 100dvh，顶栏和页脚固定在页面上下两端，#content-wrapper 使用 flex: 1、min-height: 0 填满剩余空间，文章在这个区域内滚动。阅读进度、目录高亮和回顶的事件源也一并改到内容区域。

text
1
2
3
4
5
6
7
8
┌──────────────────────────────────────────┐│ header                                   │├──────────────┬───────────────────────────┤│ sidebar      │ content-wrapper（滚动）     ││              │   └── article stage        │├──────────────┴───────────────────────────┤│ footer                                   │└──────────────────────────────────────────┘

这里要特别区分宽度与高度。屏幕窄不等于窗口矮：小于桌面阈值时，侧栏转换为抽屉或隐藏入口；高度较短时，则只压缩顶栏、页脚和辅助内容，不能误把桌面窗口切成手机布局。触摸设备通过 pointer: coarse 增大操作目标，而不是只凭宽度猜测输入方式。

3.2 目录不再用符号模拟层级

文章目录曾在最左边使用 >> 作为前导符。它有明显的旧式终端感，但放在新的低对比度轨道中显得过于突兀，也无法自然表达当前阅读位置。

新目录使用一条弱对比度的垂直轨道和圆点节点：普通节点保持弱文字颜色，hover 和当前章节使用强调色与轻微的光晕。层级仍由缩进和编号配置表达，不再依赖重复的装饰符号。桌面侧栏中的目录与站点概览共享同一个切换入口，按钮文字随当前视图变化，避免“按钮写着站点概览，下面却显示文章目录”的状态错位。

3.3 给日月背景留出空间

背景右侧的日月天体需要空间，但内容卡片不能因此看起来向侧边栏倾斜。这个问题在宽屏上尤其明显：第一次实现使用了安全区加 translateX 左移，虽然右侧空出来了，文章舞台却不再处于主容器中心。

后来去掉了左移，改为计算正文可用宽度。设当前主容器可用宽度为 W，主题可读宽度为 S，单侧天体安全距离为 C，则桌面正文区域宽度为：

text
1
stage = min(S, W - 2C - gutter)

左右对称扣除 C 后，卡片仍使用 margin: auto 居中。右侧不会贴近天体，左侧也不会被推向侧边栏；在侧栏隐藏的窄屏断点，安全距离归零，恢复普通单列宽度。4K 宽度下再设置单独的舞台上限，避免长文一行过长。

四、检查搜索、评论和静态页面

首页和文章页往往最先得到关注，但主题真正容易出问题的地方是低频页面和可选功能。这次样式令牌与页面骨架调整后，也逐项检查了以下内容：

国际化同样不能只翻导航菜单。页面标题、搜索占位符、空结果、倒计时、加密提示、二维码和赞赏提示都应该优先读取语言包；配置留空时才回退到该语言的默认文本。这样站点可以用一份主题配置切换语言，而不会在英文页面里突然出现“本地搜索”几个中文字。

五、构建与页面检查

主题包含 Pug、Stylus、浏览器 ES Module、Hexo filter、injector 和 generator。直接执行某个 JS 文件，无法证明 Hexo 的配置合并、页面生成、资源注入和最终选择器仍然正确。因此这轮验证一直以 Hexo CLI 为核心。

bash
1
2
3
4
5
6
# 在博客根目录npm run cleannpm run build# 在主题目录node tests/theme-contract.test.js

契约测试覆盖了子路径资源、外观策略、搜索与静态页面开关、加密、站点地图、robots、本地搜索、语言包和 themeinit 配置初始化等场景。它不替代浏览器测试，但可以防止模板/配置/注入层在重构后悄悄失配。

浏览器端则分别检查首页、长文、带目录文章、归档、标签/分类、搜索、404、加密和重定向页面，并覆盖夜间、日间和系统跟随模式。重点视口包括常规桌面、短高度窗口、横向平板、手机和 4K 宽屏。对于天体安全区这类几何问题，还需要在真实构建页面中检查卡片中心线、侧栏距离和天体边界，而不能只相信 CSS 的字面公式。

六、小结

这次主要补齐了日间配色，整理了颜色配置和脚本位置，并把文章滚动、目录进度和回顶统一到内容区域。修改主题布局时，短窗口和宽屏都需要单独检查，尤其是日月背景与正文之间的留白，只看常规桌面尺寸容易漏掉问题。

在 Homelab 搭建手记（6）Debian Xfce 与 XRDP 同用户并发会话配置 中，我已经把 Debian、XFCE 和 XRDP 的远程桌面环境调整到可以长期使用；上一篇又通过 Homelab 搭建手记（7）部署 code-server 并配置 HTTPS 访问 把浏览器开发环境接了出来。

不过 code-server 只能提供编辑器和终端，遇到必须使用完整图形界面的程序时，还是需要打开原生 RDP 客户端。这次增加一个浏览器入口：使用 Apache Guacamole 作为 Web Gateway，通过 RDP 连接已有的 xrdp 会话。这样既保留原生 RDP，也可以在平板、轻薄本或临时设备上直接用浏览器进入 Debian 桌面。

配套脚本放在我维护的 homelab-setup 项目中。这个仓库用于初始化 Debian 环境和部署常用服务；这次加入 Guacamole 时，我也整理了有状态服务的目录管理，让生成的配置有固定位置，重新执行脚本时保留已有账号和连接数据。下面会同时说明脚本用法和具体配置。

一、目标架构

Guacamole 连接的是现有的远程 XFCE 会话，访问链路如下：

text
1
2
3
4
5
6
7
8
9
10
11
12
13
浏览器  │ HTTPS  ▼Caddy  │ 反向代理  ▼Apache Guacamole  │ RDP  ▼xrdp  │  ▼已有的 XFCE 远程会话

xrdp 是远程桌面后端，Guacamole 把浏览器连接转换为 RDP，Caddy 负责 HTTPS 和外部入口。原生 RDP 客户端仍然可以直接连接 xrdp，两种访问方式互不替代。

二、为什么选择 Guacamole

如果只是想在浏览器中显示一个 Linux 桌面，也可以选择专门的 Web Desktop 容器。但那通常意味着重新创建用户、桌面环境和数据目录，和当前已经调通的 xrdp 会话变成两套互不相干的系统。

Guacamole 更适合当前场景，因为它只负责把浏览器连接转发为 RDP，不需要安装另一套桌面。这样可以保留之前已经验证过的本地与远程会话共存、同用户会话复用，以及输入法、D-Bus 和密钥环等配置。Guacamole 自身通过 Docker 隔离，也不会向宿主机额外安装 Tomcat、Java 或 PostgreSQL 运行时。

三、为什么把有状态服务统一放在 services/docker/

过去部署 Docker 服务时，Compose 文件有时放在 /opt，有时放在用户目录。服务多了，就不容易记住配置、环境变量和初始化 SQL 分别放在哪里，备份时也容易漏掉。因此这次把生成的服务配置统一放到 services/docker/ 下，每个服务使用自己的子目录。

因此我在 homelab-setup 中把服务入口和数据工作区分开：setup/ 保存可公开的安装与生成脚本，工作区中的 services/docker/ 保存本机服务配置；镜像和 PostgreSQL volume 仍由 Docker 管理，不会被错误地当成 Git 内容提交。

默认目录关系如下：

text
1
2
3
4
5
6
7
8
~/workspace/├── setup/                              # 公开的 homelab-setup 仓库└── services/    └── docker/        └── guacamole/                  # 本机有状态服务配置            ├── compose.yaml            ├── .env                    # 本机凭据，权限 600，不提交            └── initdb.sql

数据工作区默认是 $HOME/workspace，需要换到数据盘时可使用 --workspace-root 统一指定，省去逐个修改服务路径的操作。备份时要保存这里的 Compose 文件和 .env，并单独备份 Docker volume 中的数据。

Compose 文件本身占用很小空间，PostgreSQL 数据和镜像层实际位于 Docker 默认数据目录。部署前可以检查：

bash
1
2
sudo du -sh /var/lib/docker 2>/dev/nulldocker system df

四、通过 homelab-setup 部署并复用服务状态

我为 homelab-setup 增加了 services/docker/00-guacamole.sh。它先检查 Docker 与 Docker Compose，再在上述目录中生成缺失的部署文件、校验 Compose 配置并启动容器。重复执行时不会覆盖已有 .env、initdb.sql 或数据库卷；默认只拉取本地缺少的固定版本镜像，只有显式使用 --upgrade 才会拉取更新。

克隆公开仓库后，在仓库目录执行：

bash
1
2
3
4
5
6
7
8
git clone https://github.com/DoraTiger/homelab-setup.git "$HOME/workspace/setup"cd "$HOME/workspace/setup"# 按编号选择 Guacamole 服务bash service.sh --silent docker 00# 数据工作区位于其他磁盘时# bash service.sh --silent --workspace-root /data/homelab docker 00

执行完成后，日常管理回到生成的服务目录：

bash
1
2
3
4
cd "$HOME/workspace/services/docker/guacamole"docker compose psdocker compose logs -fdocker compose restart

如果不使用脚本，下面就是它所实现的关键原理。Guacamole 的 PostgreSQL 表结构由官方镜像生成，并固定版本以避免 latest 标签在升级时悄悄改变行为：

bash
1
2
3
4
docker run --rm guacamole/guacamole:1.6.0 \  /opt/guacamole/bin/initdb.sh --postgresql > initdb.sqlls -lh initdb.sqlhead initdb.sql

脚本会自动生成随机数据库密码并以 600 权限保存到部署目录的 .env。数据库密码只放在本机的 .env 中，不写入文章、Compose 文件或 Git 仓库：

bash
1
chmod 600 "$HOME/workspace/services/docker/guacamole/.env"

dotenv
1
GUACAMOLE_DB_PASSWORD=替换为随机生成的密码

五、编排 Guacamole、guacd 与 PostgreSQL

compose.yaml 由三个容器组成：postgres 保存用户和连接配置，guacd 负责协议代理，guacamole 提供 Web 界面。

yaml
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
services:  postgres:    image: postgres:17    restart: unless-stopped    environment:      POSTGRES_DB: guacamole_db      POSTGRES_USER: guacamole_user      POSTGRES_PASSWORD: ${GUACAMOLE_DB_PASSWORD}    volumes:      - postgres-data:/var/lib/postgresql/data      - ./initdb.sql:/docker-entrypoint-initdb.d/001-guacamole.sql:ro    networks: [guacamole]  guacd:    image: guacamole/guacd:1.6.0    restart: unless-stopped    networks: [guacamole]  guacamole:    image: guacamole/guacamole:1.6.0    restart: unless-stopped    depends_on: [postgres, guacd]    environment:      GUACD_HOSTNAME: guacd      POSTGRESQL_ENABLED: "true"      POSTGRESQL_HOSTNAME: postgres      POSTGRESQL_DATABASE: guacamole_db      POSTGRESQL_USERNAME: guacamole_user      POSTGRESQL_PASSWORD: ${GUACAMOLE_DB_PASSWORD}      WEBAPP_CONTEXT: ROOT    ports:      - "127.0.0.1:30090:8080"    networks: [guacamole]networks:  guacamole:volumes:  postgres-data:

setup 模板设置了 WEBAPP_CONTEXT: ROOT，因此 Guacamole 直接位于 /。端口映射使用 127.0.0.1:30090:8080，宿主机上的 Web 端口只监听回环地址，浏览器通过 Caddy 访问。

30090 延续了 homelab-setup 使用高位端口的约定，前文的 code-server 对应 30080。这样可以减少与常见低位端口的冲突，也便于区分反向代理的目标服务。高位端口本身不提供安全保护，仍需保留回环地址绑定和 HTTPS 配置。手动编写 Compose 文件时，也应与脚本生成的路径和端口保持一致。

启动并检查容器：

bash
1
2
3
4
5
cd "$HOME/workspace/services/docker/guacamole"docker compose up -ddocker compose pscurl -I http://127.0.0.1:30090docker compose logs --tail=100

六、通过 Caddy 提供 HTTPS

浏览器远程桌面和 code-server 一样，需要一个稳定的 HTTPS 域名。实际部署时将示例域名替换成自己的域名：

本文沿用前文的证书签发方式：由 Caddy 通过阿里云 DNS-01 完成域名验证和 SSL 证书签发，alidns 插件读取阿里云 DNS API 凭据。也就是说，下面的配置适用于当前使用阿里云 DNS 的环境；如果改用 Cloudflare、腾讯云或其他 DNS 服务商，需要将 alidns 插件和对应的凭据配置一并替换，不能只修改域名。

caddy
1
2
3
4
5
6
7
8
9
10
desktop.example.com {    tls {        dns alidns {            access_key_id {env.ALIYUN_ACCESS_KEY_ID}            access_key_secret {env.ALIYUN_ACCESS_KEY_SECRET}        }    }    reverse_proxy 127.0.0.1:30090}

bash
1
2
sudo caddy validate --config /etc/caddy/Caddyfilesudo systemctl reload caddy

Caddy 原生支持 WebSocket 反向代理，不需要手动添加 Upgrade 和 Connection 请求头。访问 https://desktop.example.com/ 后，应该能看到 Guacamole 登录页。

七、首次登录与 RDP 连接

初始化数据库后，Guacamole 的初始管理员账号是 guacadmin，初始密码也是 guacadmin。首次登录后，应立即新建一个自己的管理员账号并授予全部管理权限；退出后用新账号重新登录，确认权限和连接配置都正常，再删除默认的 guacadmin 账号。管理密码、RDP 密码和 DNS API 凭据不要复用，也不要把默认账号留在长期运行的实例中。

在 Settings → Connections → New Connection 中创建连接：

text
1
2
Name: Debian XFCEProtocol: RDP

连接由 guacd 容器发起，因此不能填写 127.0.0.1。对 guacd 来说，这个地址指向的是容器自身，而不是 Debian 宿主机。这里应该填写 Debian 在局域网中的地址：

text
1
2
Hostname: YOUR_DEBIAN_LAN_IPPort: 3389

第一次连接可以使用 Security mode: Any，并临时启用 Ignore server certificate，以兼容 xrdp 默认自签名证书。长期运行时应结合实际证书和网络边界重新评估。

八、最容易踩的坑：RDP 不要误选成 VNC

这次排障中最有代表性的问题，是浏览器能够打开 Guacamole，点击连接后却一直停留在“已连接，等待应答”。guacd 日志显示它实际创建的是：

text
1
Creating new client for protocol "vnc"

而目标端口是 xrdp 的 3389，链路就变成了：

text
1
Guacamole ── VNC ──→ Debian:3389 ──→ xrdp

协议不匹配时，xrdp 日志会出现 X.224 握手失败。这不是 xrdp 本身损坏，而是连接类型选错。重新把连接类型改为 RDP，并确认日志出现：

text
1
Creating new client for protocol "rdp"

这是判断协议是否正确的最快方法。

九、确认 WebSocket 和会话复用

连接建立后，可以在浏览器开发者工具的 Network 面板中搜索 websocket 或 tunnel，确认 /websocket-tunnel 返回 101 Switching Protocols。这说明浏览器、Caddy 和 Guacamole 之间的 WebSocket 链路正常。

正确使用 RDP 后，Guacamole 可以复用此前已经存在的远程 XFCE 会话。这次部署没有修改已经稳定的 /etc/xrdp/startwm.sh，也没有额外创建一套桌面环境。

十、显示、动态分辨率与剪贴板

这个浏览器入口主要用于 ChatGPT、Obsidian、浏览器和终端，连接参数应优先保证文字可读性和窗口适配：

text
1
2
3
4
5
6
7
8
9
10
11
Resize method:          Display updateColor depth:            32-bitDPI:                    96Clipboard:              BidirectionalFont smoothing:         EnabledTheming:                EnabledWallpaper:              DisabledAnimations:             DisabledFull-window drag:       DisabledDrive redirection:      Disabled unless neededAudio:                  Enable only if needed

Display update 会在浏览器窗口大小变化时请求远程桌面调整分辨率。Guacamole 使用 Canvas 显示远程画面，清晰度不一定完全等同于原生 RDP 客户端；浏览器缩放建议保持 100%，再根据实际显示器测试 DPI。

十一、最终访问体系

text
1
2
3
4
5
原生 RDP 客户端 ─────────────→ xrdp ──→ XFCE浏览器 ─→ HTTPS ─→ Caddy ─→ Guacamole ─→ RDP ─→ xrdp ──→ XFCE浏览器 ─→ HTTPS ─→ Caddy ─→ code-server

日常长时间使用时，我还是更倾向于原生 RDP，画质和延迟表现更好；临时设备、平板或无法安装客户端时，再通过 Guacamole 连接。

十二、维护与安全边界

bash
1
2
3
4
5
6
7
8
cd "$HOME/workspace/services/docker/guacamole"docker compose psdocker compose logs --tail=100docker compose logs -f guacddocker compose restartdocker compose downdocker compose up -ddocker system df

长期运行时需要注意：PostgreSQL volume 保存用户、连接、权限和连接参数，必须纳入备份；.env 权限应保持为 600；30090 继续只监听 127.0.0.1；真实客户端 IP 经过 Caddy 和 Docker bridge 后可能被代理地址替代，审计和暴力破解防护需要结合实际代理链路验证。

参考

• Apache Guacamole 官方文档
• Apache Guacamole Docker 镜像
• homelab-setup
• DoraTiger 主题 GitHub
• Caddy reverse_proxy 文档

在 HEXO 开发笔记（6）自建主题：核心功能实现 中，已经记录过主题统计功能从 localStorage 迁移到卜算子，再迁移到自建 counter 的过程。当时的实现能够满足日常使用，但计数数据主要停留在内存中，服务重启后 UV 会重新开始，配置和数据库迁移也还比较粗糙。

这次整理 doratiger-counter，主要补上了 UV 持久化、数据库迁移和退出前同步，也调整了来源校验，避免字符串匹配放过不该接受的域名。下面记录这些改动，以及 DoraTiger 主题如何调用统计接口。

一、为什么不继续使用第三方统计

最早的统计方案是浏览器端 localStorage。它不需要后端，部署成本最低，但统计数据只存在当前浏览器中，换设备或清理浏览器数据后就无法连续累计。后来接入卜算子，站点和页面的统计可以集中保存，但计数脚本依赖外部服务，服务可用性、网络环境和返回格式都不是主题能够控制的。

我的博客只需要站点和文章的 PV/UV，用一个 Go 程序加一个 SQLite 数据库文件就可以实现。主题通过 HTTP API 读取计数，统计口径和升级方式由自己维护，出了问题也方便检查代码和数据库。

二、整体结构

doratiger-counter 目前由三层组成：

text
1
2
3
4
5
浏览器中的 DoraTiger 主题  → GET /count?page=<path>&uid=<visitor-id>  → Go HTTP 服务  → 内存计数器与访客集合  → SQLite（定时同步，退出时最后同步）

主题负责生成访问者标识和当前页面路径，服务端负责校验来源、递增计数并返回结果，数据库只负责保存可恢复的数据。这样划分以后，主题不需要知道数据库结构，服务端也不需要参与 Hexo 构建过程。

当前版本有两个接口：

http
1
2
GET /count?page=/posts/example/&uid=visitor-idOrigin: https://blog.example.com

json
1
2
3
4
5
6
{  "site_pv": 42,  "page_pv": 3,  "site_uv": 12,  "page_uv": 2}

page 是必填的页面键，uid 可选。没有 uid 时仍然会增加 PV，但不会增加 UV。另一个接口是 GET /health，只返回 {"status":"ok"}，不要求请求带有站点来源，方便反向代理或监控系统做健康检查。

三、PV 与 UV 如何统计

3.1 PV 使用内存计数器

请求到达后，站点 PV 和当前页面 PV 都在内存中递增。服务每 30 秒把站点计数、页面计数和访客集合放进同一个事务写入 SQLite。收到 SIGTERM 或 Ctrl-C 时，HTTP 服务先停止接收新请求，再触发一次最后同步。

这种做法避免了每次页面访问都执行数据库写操作，适合个人站点的低到中等访问量。但它也意味着：如果进程被强制杀死，最近一次同步之后的计数可能丢失，最大窗口约为 30 秒。因此这套服务适合展示型统计，不适合财务、计费或审计场景。

3.2 UV 使用持久化摘要去重

主题第一次访问时在浏览器中生成一个 UUID，并通过 Cookie 保存一年。之后每次请求都把这个 UUID 作为 uid 发送给服务端。服务端不会保存原始 UUID，而是计算 SHA-256 摘要，再将摘要分别放进站点访客集合和页面访客集合中。

这样做有两个直接效果：同一个访客再次打开页面时，页面 PV 会增加，但页面 UV 不会重复增加；服务重启后，访客集合可以从数据库恢复，站点 UV 不会从零开始。摘要仍然是可以关联的假名标识，所以它不是“完全匿名数据”，部署时仍然应该在隐私说明中告知访客用途。

四、来源限制与 CORS

统计接口不是登录接口，但至少可以减少普通网页和脚本的误调用。配置 allowed_origins 后，服务会解析 Origin 或缺失时使用的 Referer，只按规范化后的主机名精确匹配允许列表：

toml
1
2
3
4
[counter]site_key = 'dtc_site'allowed_origins = ['blog.example.com']enable_cors = true

这里有两个容易混淆的边界。第一，example.com 和 example.com.evil.test 不能按字符串包含关系判断，否则恶意后缀也可能通过。第二，Origin/Referer 可以被直接构造 HTTP 客户端伪造，所以它只能作为来源限制，不能当作身份认证，更不能用于授权、计费或其他安全决策。

开启 CORS 后，服务只会为通过白名单校验的来源返回 Access-Control-Allow-Origin，并带上 Vary: Origin。如果统计服务和博客由同一个反向代理提供，通常不需要打开宽泛的跨域策略。

五、数据库迁移与恢复

数据库使用单调递增的 schema version。初始版本包含四类数据：页面 PV、站点 PV、站点访客摘要和页面访客摘要。启动时先检查数据库版本，再执行只增加表结构的迁移；如果发现数据库版本高于当前程序，服务会拒绝启动，避免旧程序误操作新数据。

对于早期只有 page_stats 和 site_stats 两张表的数据库，当前迁移会保留原有 PV，再补齐访客表。服务启动时将已有数据加载到内存，后续请求继续从原来的数值上递增。升级服务前仍建议同时备份 counter.db、counter.db-wal 和 counter.db-shm 文件。

六、主题中的接入方式

主题配置只需要指定统计类型和 API 地址：

yaml
1
2
3
4
5
6
statistics:  enable: true  type: counter  counter:    api: https://counter.example.com/count    uv: true

footer.pug 在文章页和普通页面中渲染统计占位符，浏览器脚本读取或创建 dtc_uid，再把 location.pathname 和访客标识拼到 API 请求中。请求成功时显示服务端返回的 site_uv、page_uv；请求失败或没有配置 API 时，则退回到 localStorage 的本地方案。

这个 fallback 很重要：统计服务短暂不可用时，主题不会因为一个附加功能失败而影响文章阅读。但两种方案的统计口径不同，localStorage 只知道当前浏览器访问过哪些路径，不能与服务端的站点总量直接比较，所以它更适合作为临时占位，而不是长期数据源。

七、部署边界与当前限制

服务可以直接运行，也可以通过 Docker 部署。生产环境建议让它监听内网地址，由 Caddy、Nginx 等反向代理提供 HTTPS，并限制后端端口的可访问范围。数据库目录需要持久化挂载，容器更新时不能把 /app/data 一并丢弃。

当前版本刻意保持简单，也保留了几个明确限制：

• 只支持 SQLite，面向单实例和个人站点；
• 计数先写内存，再定时同步，异常退出存在短暂数据窗口；
• 访客摘要和页面访客集合会随访客量增长，暂不适合大规模多租户部署；
• 不提供后台管理页面、历史报表和数据导出接口；
• 来源白名单不是认证机制，不能防止有意伪造请求。

目前我仍按单实例维护。外部数据库、后台报表和多实例协调暂时没有实际需求，后面根据访问量再考虑。

八、总结

整理之后，统计服务可以从数据库恢复访客集合，升级时处理旧表结构，正常退出前也会同步内存计数。日常使用仍需备份数据库，并注意异常退出可能丢失尚未同步的数据。对我目前的博客来说，这些已经够用了。

参考

• DoraTiger 主题 GitHub
• Hexo 官方文档
• Go database/sql 文档
• SQLite 官方文档

在之前的 Homelab 搭建手记（4）开发工具配置 中，我已经把 VS Code、Codex CLI 等开发工具整理到了 Debian 工作站上。不过桌面远程只是其中一种使用方式：当手边只有平板、轻薄本，或者不方便建立完整的远程桌面时，如果能直接在浏览器中打开开发环境，会更加灵活。

code-server 可以把接近 VS Code 的编辑体验放进浏览器，终端、代码和扩展仍运行在 Homelab 主机上。最开始我直接通过内网 IP 和端口访问，编辑与终端都能使用，看起来部署已经结束；直到在其中运行 Codex 扩展，才发现 WebView 无法正常拉起，并提示当前页面不是安全上下文。

为了解决这个问题，我用 Caddy + AliDNS DNS-01 配置了 HTTPS，并把 code-server 改为只监听本机。本文从安装开始，记录 HTTPS 配置和 Codex 扩展的检查过程。相关安装脚本放在 homelab-setup 项目中，可以配合下面的步骤使用。

一、从“能够打开”到“能够正常开发”

1.1 普通 HTTP 下的问题

直接访问下面这样的地址时，code-server 本身可以正常显示：

text
1
http://<SERVER_IP>:<PORT>

登录、编辑文件和使用终端通常没有问题，但 Codex 扩展的 WebView 可能无法工作，浏览器控制台会出现与 crypto.subtle 或 Service Worker 有关的错误。code-server 官方 FAQ 也说明，WebView 依赖 Service Worker，而 Service Worker 需要运行在 Secure Context 中。

可以在浏览器开发者工具中检查：

javascript
1
2
window.isSecureContextwindow.crypto.subtle

通过普通内网 IP 的 HTTP 页面访问时，结果可能是：

text
1
2
falseundefined

这也是最初容易误判的地方：code-server 进程已经正常运行，不代表其中所有浏览器能力都可用。 如果只是看服务状态或登录页面，很难发现这条链路还缺少 HTTPS。

1.2 最终部署目标

本文使用的结构如下：

text
1
2
3
4
5
6
7
8
9
10
11
12
浏览器  │  │ HTTPS  ▼code.example.com  │  ▼Caddy :443  │  │ HTTP，仅本机回环  ▼code-server 127.0.0.1:30080

职责划分为：

• code-server 提供编辑器、终端和扩展运行环境；
• code-server 只监听 127.0.0.1，不直接暴露应用端口；
• Caddy 负责 TLS 终结和反向代理；
• AliDNS Provider 负责完成 ACME DNS-01 验证；
• 浏览器只通过 https://code.example.com 访问服务。

这里的 code.example.com、30080 都是示例值，需要按自己的域名和端口替换。本文不会展示实际使用的域名、IP、凭据或内部拓扑。

二、安装 code-server

2.1 使用自动化脚本安装

公开的 homelab-setup 中，17-code-server.sh 会从 code-server 官方 GitHub Release 获取与当前架构匹配的 Debian 安装包，并把下载结果保存在本地缓存目录中。脚本目前支持 amd64 和 arm64。

bash
1
2
3
4
5
6
# 克隆公开仓库git clone https://github.com/DoraTiger/homelab-setup.gitcd homelab-setup# 安装 code-serverbash init.sh --silent 17

如果还需要构建带 AliDNS Provider 的 Caddy，可以按照模块顺序一次执行 Go、Caddy 和 code-server：

bash
1
bash init.sh --silent 05 16 17

其中 05 提供 Go 工具链，16 安装 Caddy 并加入 dns.providers.alidns，17 安装 code-server。Caddy 自定义构建当前要求 Go 1.25 或更高版本，脚本会在修改系统前检查这个条件。

自动化脚本有意只完成软件安装，不会：

• 收集域名或 AliDNS AccessKey；
• 修改用户现有的 code-server 配置；
• 自动启动 code-server 服务；
• 把站点配置写入 Caddyfile。

这些内容与每台主机的域名、端口和安全策略有关，保留为显式配置比隐藏在安装脚本中更稳妥。

2.2 手动安装方式

如果不使用脚本，也可以从 code-server Releases 下载对应架构的 Debian 安装包：

bash
1
sudo apt install ./code-server_<VERSION>_<ARCH>.deb

安装完成后检查版本：

bash
1
code-server --version

这里只确认程序已经安装，不急着直接运行。下一步先固定监听地址和认证方式，避免默认配置与最终服务状态不一致。

三、配置并启动 code-server

3.1 配置监听地址

code-server 的用户配置位于：

text
1
~/.config/code-server/config.yaml

编辑配置文件：

bash
1
2
mkdir -p ~/.config/code-server${EDITOR:-nano} ~/.config/code-server/config.yaml

参考配置如下：

yaml
1
2
3
4
5
bind-addr: 127.0.0.1:30080auth: passwordpassword: <STRONG_PASSWORD>cert: falselocale: zh-cn

各项含义为：

• bind-addr：只监听本机回环地址，端口可以自行调整；
• auth：保留 code-server 自身的密码认证；
• password：替换为独立的强密码，不要提交到 Git；
• cert: false：code-server 不直接处理 TLS，由 Caddy 统一负责；
• locale：将界面语言设置为简体中文。

配置文件包含登录密码，建议限制权限：

bash
1
chmod 600 ~/.config/code-server/config.yaml

3.2 使用 systemd 管理服务

Debian 安装包提供了用户实例化的 systemd 服务，可以使用当前用户名启用：

bash
1
sudo systemctl enable --now code-server@$USER

检查运行状态和日志：

bash
1
2
systemctl status code-server@$USER --no-pagerjournalctl -u code-server@$USER -n 100 --no-pager

修改 config.yaml 后，需要重启正在运行的服务：

bash
1
sudo systemctl restart code-server@$USER

仅修改配置文件不会让旧进程自动切换端口，这一点也是后续出现 502 Bad Gateway 的常见原因。

3.3 先验证本地服务

在加入 Caddy 前，先确认 code-server 自身可用：

bash
1
2
ss -lntp | grep ':30080'curl --noproxy '*' -I http://127.0.0.1:30080

正常情况下可以看到 code-server 只监听 127.0.0.1:30080，HTTP 请求返回登录页跳转：

text
1
2
HTTP/1.1 302 FoundLocation: ./login

如果这一步失败，应该先检查 code-server 的配置与日志，而不是继续调整 Caddy。把应用层和代理层分开验证，可以避免在多个组件之间来回猜测。

四、为什么 HTTPS 需要 DNS-01

4.1 内网服务无法使用常规公网验证

本文希望使用公网可信证书，但 code-server 仍然只在内网访问。域名可以通过 DNS 解析到 RFC 1918 私网地址，例如：

text
1
code.example.com  A  <PRIVATE_IP>

这种情况下，公共证书颁发机构无法从公网访问该私网地址。依赖公网访问 80 端口的 HTTP-01，以及依赖公网访问 443 端口的 TLS-ALPN-01，都不适合这套纯内网架构。

DNS-01 验证的是域名 DNS 中临时创建的 TXT 记录：

text
1
2
3
4
5
6
7
8
9
10
Caddy  │ AliDNS API  ▼_acme-challenge.code.example.com  TXT  <CHALLENGE_VALUE>  │  ▼证书颁发机构查询 TXT 记录  │  ▼验证域名控制权并签发证书

根据 Caddy 官方文档，DNS Challenge 不要求开放入站端口，申请证书的服务器也不需要从公网可达，因此正好适合“公网域名 + 私网服务”的场景。

4.2 为什么选择 Caddy

我用 Caddy 配置 HTTPS，主要考虑以下几点：

• Automatic HTTPS 会管理证书申请和续期；
• Caddyfile 中反向代理配置较短；
• 可以通过 DNS Provider 扩展接入 AliDNS；
• WebSocket 反向代理不需要额外堆叠大量配置；
• 配置适合使用 fmt → validate → reload 的固定流程维护。

如果环境里已经稳定运行 Nginx、Traefik 或其他代理，没有必要为了 code-server 强行迁移。本文选择 Caddy，只是因为它在这台个人 Debian 工作站上用较低的配置成本补齐了 HTTPS。

五、安装带 AliDNS Provider 的 Caddy

5.1 标准二进制不包含 AliDNS 模块

Caddy 的 DNS Provider 属于扩展模块，标准发行版不一定包含 dns.providers.alidns。安装后可以检查：

bash
1
caddy list-modules | grep '^dns.providers.alidns$'

没有输出时，需要使用 xcaddy 构建自定义二进制：

bash
1
2
3
4
go install github.com/caddyserver/xcaddy/cmd/xcaddy@latestxcaddy build \  --with github.com/caddy-dns/alidns

构建完成后，应先验证产物再替换系统版本：

bash
1
./caddy list-modules | grep '^dns.providers.alidns$'

本文使用的 16-caddy.sh 自动化模块会完成以下工作：

1. 安装 Caddy 官方 Debian 包，保留发行版提供的用户、目录和 systemd 服务；
2. 检查当前二进制或本地缓存是否已经包含 AliDNS Provider；
3. 必要时通过 xcaddy 构建自定义 Caddy；
4. 使用 dpkg-divert 和 update-alternatives 管理官方与自定义二进制；
5. 验证模块存在后才报告安装完成。

这样既不直接破坏 Debian 软件包的管理关系，也能在重复执行时复用已经验证过的自定义构建。

5.2 安装模块

只安装 Caddy 时执行：

bash
1
2
cd homelab-setupbash init.sh --silent 05 16

安装后检查：

bash
1
2
3
caddy versioncaddy list-modules | grep '^dns.providers.alidns$'systemctl status caddy --no-pager

如果系统已有包含其他第三方模块的 Caddy，升级前应检查 caddy build-info。不能为了补一个 AliDNS 模块，静默覆盖掉用户已有的其他扩展。

六、配置 code-server 的 HTTPS 入口

6.1 保存 AliDNS 凭据

不要把 AccessKey 直接写进 Caddyfile，更不能提交到仓库。创建单独的环境文件：

bash
1
2
sudo install -m 640 -o root -g caddy /dev/null /etc/caddy/alidns.envsudoedit /etc/caddy/alidns.env

使用 AliDNS Provider 当前支持的环境变量名称：

text
1
2
ALIYUN_ACCESS_KEY_ID=<ACCESS_KEY_ID>ALIYUN_ACCESS_KEY_SECRET=<ACCESS_KEY_SECRET>

建议为自动 DNS 验证创建独立的阿里云 RAM 身份，并限制到实际需要的 DNS 权限，不使用主账号 AccessKey。检查文件权限：

bash
1
sudo stat -c '%A %U:%G %n' /etc/caddy/alidns.env

预期为：

text
1
-rw-r----- root:caddy /etc/caddy/alidns.env

6.2 通过 systemd 注入凭据

不要直接修改软件包提供的 systemd unit，否则升级时可能被覆盖。使用 override：

bash
1
sudo systemctl edit caddy

写入：

ini
1
2
3
4
[Service]EnvironmentFile=/etc/caddy/alidns.envExecStart=ExecStart=/usr/bin/caddy run --config /etc/caddy/Caddyfile

这里空的 ExecStart= 用来清除原启动命令，再定义不带 --environ 的启动方式。Debian 的 Caddy unit 曾使用 caddy run --environ 输出运行环境；如果把 AccessKey 通过 EnvironmentFile 注入，同时保留该参数，敏感值可能进入 journal。

应用 override 前可以检查合并结果：

bash
1
2
sudo systemctl daemon-reloadsystemctl cat caddy

如果凭据曾经完整出现在终端记录、日志或其他非安全位置，仅删除日志并不足够，应立即轮换对应 AccessKey。

6.3 配置 Caddyfile

编辑 /etc/caddy/Caddyfile：

caddy
1
2
3
4
5
6
7
8
9
10
code.example.com {    tls {        dns alidns {            access_key_id {env.ALIYUN_ACCESS_KEY_ID}            access_key_secret {env.ALIYUN_ACCESS_KEY_SECRET}        }    }    reverse_proxy 127.0.0.1:30080}

浏览器到 Caddy 使用 HTTPS，Caddy 到本机 code-server 使用 HTTP：

text
1
Browser ──HTTPS──> Caddy ──HTTP──> 127.0.0.1:30080

因为 code-server 已经配置为 cert: false，所以 reverse_proxy 不应误写成 https://127.0.0.1:30080。回环接口上的这一跳不需要重复配置 TLS。

6.4 格式化、验证并启动

每次修改 Caddyfile 后固定执行：

bash
1
2
3
4
5
sudo caddy fmt --overwrite /etc/caddy/Caddyfilesudo caddy validate \  --config /etc/caddy/Caddyfile \  --adapter caddyfilesudo systemctl restart caddy

首次申请证书需要创建 DNS TXT 记录，等待 DNS 传播可能需要一段时间。查看日志：

bash
1
sudo journalctl -u caddy -n 100 --no-pager

确认日志中的验证类型是 dns-01，并检查是否出现权限不足、TXT 传播超时或 ACME 限流。

七、分层验证完整链路

7.1 DNS 与本地 upstream

先确认域名解析到了预期的私网地址：

bash
1
dig +short code.example.com

再绕过代理环境变量，直接检查 code-server：

bash
1
curl --noproxy '*' -I http://127.0.0.1:30080

只要这一步不是正常的登录跳转，就不应该继续判断 TLS 或 Caddy。

7.2 HTTPS 与反向代理

检查完整入口：

bash
1
curl --noproxy '*' -Iv https://code.example.com

重点观察：

• 证书主机名与域名一致；
• 证书链能够通过校验；
• HTTP 响应来自 Caddy；
• 最终返回 code-server 登录页或对应跳转，而不是 502。

完成登录后，再在浏览器 Console 检查：

javascript
1
2
window.isSecureContextwindow.crypto.subtle

预期分别得到：

text
1
2
trueSubtleCrypto

八、实际遇到的问题

8.1 HTTPS 正常但出现 502

如果浏览器显示的证书有效，但响应为：

text
1
2
HTTP/2 502server: Caddy

说明浏览器到 Caddy 的 TLS 链路已经正常，问题位于 Caddy 到 code-server 的 upstream：

text
1
2
Browser ──HTTPS──> Caddy    正常Caddy ──HTTP──> code-server 异常

本次部署中的原因是修改了 code-server 的监听端口，却没有重启旧进程。按顺序检查：

bash
1
2
3
4
sudo systemctl restart code-server@$USERss -lntp | grep ':30080'curl --noproxy '*' -I http://127.0.0.1:30080sudo journalctl -u caddy --since '5 minutes ago' --no-pager

同时确认 Caddyfile 中的端口一致，且 upstream 协议没有误写成 HTTPS。

8.2 Caddy 的 2019 端口冲突

Caddy 默认在 127.0.0.1:2019 提供 Admin API，它不是 code-server 的业务端口。若日志出现：

text
1
listen tcp 127.0.0.1:2019: bind: address already in use

通常意味着系统里已经存在另一个 Caddy 进程。检查：

bash
1
2
sudo ss -lntp | grep ':2019'ps aux | grep '[c]addy'

不要简单把 Admin API 改到 2020 来绕过，因为两个实例仍可能继续竞争 80 和 443。正确做法是找出手工启动或遗留的实例，只保留 systemd 管理的一份 Caddy。

Admin API 应只监听本机，不要暴露到 LAN 或公网。

8.3 代理变量干扰 curl 判断

如果系统配置了 http_proxy 或 https_proxy，直接执行 curl 可能经过代理，得到的结果不能准确表示本机链路。排查时显式加入：

bash
1
2
curl --noproxy '*' -I http://127.0.0.1:30080curl --noproxy '*' -Iv https://code.example.com

这样才能分别观察本地 upstream 和完整 HTTPS 入口。日常环境中也可以合理配置 NO_PROXY，但不要为了排障临时清空或覆盖整套代理配置。

8.4 AccessKey 出现在 journal

如果发现 Caddy 启动日志打印了完整环境变量，应立即：

1. 停止继续复制或分享相关日志；
2. 检查 systemd 实际的 ExecStart 是否包含 --environ；
3. 使用 override 移除该参数；
4. 在阿里云 RAM 控制台轮换已经暴露的 AccessKey；
5. 重新验证 Caddy 能否完成 DNS-01。

把凭据移出 Caddyfile 只是第一步，还要检查凭据在进程启动、日志和故障排查路径中是否会被再次输出。

九、适用边界与总结

配置完成后，各部分的关系如下：

text
1
2
3
4
5
6
7
8
9
10
11
安装 code-server  ↓仅监听 localhost 并启用认证  ↓验证本地 HTTP upstream  ↓Caddy + AliDNS DNS-01 获取可信证书  ↓通过 HTTPS 反向代理 code-server  ↓验证 Secure Context、WebView 与 Codex 扩展

这套方案适合拥有公开域名、DNS 托管在 AliDNS、服务实际只在内网访问的个人工作站或 Homelab。DNS-01 解决的是证书验证问题，不会自动赋予外网访问能力；域名解析、路由和防火墙仍决定哪些客户端能够连接到服务。

同时，HTTPS 和 code-server 密码也不是完整的公网暴露防护。如果需要从互联网直接访问，仍应结合 VPN、身份代理、访问控制、速率限制和网络边界设计。code-server 官方也明确不建议在缺少认证与加密的情况下直接暴露服务。

这次容易漏掉的是扩展检查：编辑器和终端能用，并不代表网页也能加载。部署后除了检查登录页，还要实际打开扩展面板，确认浏览器的安全上下文和 Web Crypto 均可用。

参考

• code-server 官方安全访问指南
• code-server FAQ
• Caddy Automatic HTTPS
• Caddy AliDNS Provider
• MDN：Crypto.subtle
• DoraTiger/homelab-setup
• homelab-setup：code-server 安装模块
• homelab-setup：Caddy 安装模块

在之前的 Homelab 搭建手记（2）更换无线网卡与 XRDP WiFi 扫描授权问题 中，记录过 XRDP 环境下的 WiFi 扫描授权问题。当时发现本地自动登录的 Xfce 和远程 Xfce 同时运行时容易出现 D-Bus、polkit 等额外冲突，所以给出的阶段性建议是关闭本地自动登录，只保留单一的 XRDP 图形会话。

不过实际使用中，偶尔还是需要让物理显示器上的本地桌面保持登录，同时从其他设备通过 RDP 进入同一个用户的独立桌面。经过日志排查和反复测试，发现第二个 Xfce 会话复用了已有图形会话的环境，端口、密码认证和 Xorg 显示编号都没有问题。

本文记录如何在 Debian 13 + Xfce + XRDP 环境中，让同一个 Linux 用户同时保持本地与远程两个桌面，并进一步补齐 Fcitx5 中文输入和 GNOME Keyring，使 VS Code、GitHub Copilot 等依赖系统密钥环的应用也能在远程桌面中正常使用。相关配置已经整合进公开的 homelab-setup 项目，可以通过脚本自动完成。

一、问题现象与目标

1.1 同用户登录时黑屏退出

最初的故障现象比较固定：

• 用户没有在本地登录时，RDP 可以正常进入 Xfce；
• 用户已经在本地登录后，再使用同一用户登录 RDP，输入密码后出现黑屏；
• 黑屏持续一段时间后，远程连接自动断开；
• 注销其中一个桌面后，另一个桌面又能正常登录。

排查日志后可以看到，远程的 Xorg :10 已经成功启动，分辨率也已经完成设置，随后运行到了 startwm.sh 和 xfce4-session。但第二个 xfce4-session 很快退出，xrdp-sesman 随之关闭远程 Xorg。

这说明认证和 xorgxrdp 基本正常，真正失败的位置在远程 Xfce 会话初始化阶段。

1.2 实测环境

本文配置基于以下环境完成验证：

text
1
2
3
4
5
Debian        13.6Xfce          4.20xfce4-session 4.20.2xrdp          0.10.1xorgxrdp      0.10.2

可以通过以下命令确认系统和软件包版本：

bash
1
2
cat /etc/debian_versiondpkg -l | grep -E 'xrdp|xorgxrdp|xfce4-session'

不同 xrdp 版本支持的 session policy 可能存在差异，特别是网上常见的 Policy=UBC 多来自旧版本教程，不应在没有确认版本的情况下直接照搬。

1.3 目标不是共享同一个桌面

本文希望实现的结构是：

text
1
2
3
同一 Unix 用户├── 本地 Xfce：Xorg :0└── RDP Xfce：Xorg :10

两个桌面共享同一个 UID、文件权限和 $HOME，但各自拥有独立的：

• X11 Display；
• systemd-logind session；
• D-Bus Session Bus；
• Xfce Session Manager；
• Keyring 控制目录。

这不是让 RDP 接管物理显示器上的现有桌面。本地打开的窗口不会出现在远程桌面中，反之亦然。如果需要看到完全相同的桌面窗口，应使用桌面共享或 VNC 类方案。

二、为什么常见配置没有解决问题

2.1 ~/.xsession 只决定启动哪个桌面

很多教程会创建 ~/.xsession：

bash
1
2
printf '%s\n' 'startxfce4' > ~/.xsessionchmod +x ~/.xsession

默认启动链路大致如下：

text
1
2
3
4
5
6
7
8
9
xrdp  ↓/etc/xrdp/startwm.sh  ↓/etc/X11/Xsession  ↓~/.xsession  ↓startxfce4

这个配置回答的是“XRDP 应该启动哪个桌面环境”，并没有解决“同一个用户如何同时运行两个 Xfce session”。当远程 Xorg 已经成功创建而 xfce4-session 随即退出时，继续调整 ~/.xsession、端口或 MaxSessions 并不能触及根因。

2.2 冲突来自图形会话环境

同一个用户已经拥有本地 Xfce 后，第二个桌面可能接触到已有会话的环境，重点包括：

text
1
2
3
4
DBUS_SESSION_BUS_ADDRESSSESSION_MANAGERD-Bus Session BusXfce Session Manager

仅清除变量后重新进入 /etc/X11/Xsession，在实测环境中仍然不能形成稳定隔离。最终采用的方案是绕过默认 Xsession 启动链路，为远程 Xfce 显式创建独立的 D-Bus Session Bus：

sh
1
2
3
unset DBUS_SESSION_BUS_ADDRESSunset SESSION_MANAGERexec dbus-run-session -- /usr/local/bin/xrdp-xfce-session

其中 dbus-run-session 会为后续程序启动一个新的 Session Bus，并在桌面会话退出后结束该总线。

三、配置独立的 XRDP Xfce 会话

3.1 安装依赖

安装 XRDP、Xfce、D-Bus、输入法和密钥环组件：

bash
1
2
3
4
5
6
sudo apt updatesudo apt install \  xrdp xorgxrdp xfce4 xfce4-goodies dbus-x11 \  gnome-keyring libsecret-1-0 libpam-gnome-keyring libsecret-tools \  fcitx5 fcitx5-chinese-addons fcitx5-frontend-all \  fcitx5-config-qt im-config

本文使用 xorgxrdp。每次新建远程会话时会启动独立的 Xorg Server，而不是复用本地显示器上的 :0。

3.2 配置 sesman.ini

修改系统配置前先备份：

bash
1
sudo cp /etc/xrdp/sesman.ini /etc/xrdp/sesman.ini.bak

检查 [Sessions] 段：

ini
1
2
3
4
5
6
7
[Sessions]X11DisplayOffset=10MaxSessions=50KillDisconnected=falseDisconnectedTimeLimit=0IdleTimeLimit=0Policy=Default

这些配置分别用于：

• 从 :10 开始分配远程 Display，避开本地的 :0；
• 允许多个 XRDP session 存在；
• 客户端断开后保留远程 session；
• 不因断开或空闲超时自动结束 session；
• 使用 xrdp 0.10 实测可用的默认策略。

典型的显示编号为：

text
1
2
3
本地 Xorg：     :0第一个 RDP：    :10后续 RDP：      :11、:12……

独立 Display 只能避免 X Server 层冲突，还需要继续隔离 D-Bus 和 Xfce 会话。

3.3 配置 startwm.sh

备份 /etc/xrdp/startwm.sh：

bash
1
sudo cp /etc/xrdp/startwm.sh /etc/xrdp/startwm.sh.bak

将文件调整为：

sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
#!/bin/shif test -r /etc/profile; then    . /etc/profilefiif test -r ~/.profile; then    . ~/.profilefiunset DBUS_SESSION_BUS_ADDRESSunset SESSION_MANAGERexec dbus-run-session -- /usr/local/bin/xrdp-xfce-session

设置权限：

bash
1
sudo chmod 755 /etc/xrdp/startwm.sh

这里不再执行默认的 /etc/X11/Xsession，而是先读取系统和用户环境，再清除可能继承自其他图形会话的变量，最后在新的 D-Bus Session Bus 中启动专用包装脚本。

3.4 创建 Xfce 与 Keyring 包装脚本

在普通本地 Xfce 中，可以通过桌面自启动运行 gnome-keyring-daemon。这也是 Homelab 搭建手记（4）开发工具配置 中解决 VS Code 密钥管理问题时采用的方案。

但本文为 RDP 创建了独立的 D-Bus。原本运行在 /run/user/UID/bus 上的 Secret Service 不会自动出现在新的私有 bus 中，因此还需要在远程 bus 内启动一个独立的 gnome-keyring-daemon。

创建 /usr/local/bin/xrdp-xfce-session：

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#!/bin/bashset -euo pipefailruntime_dir="${XDG_RUNTIME_DIR:?XDG_RUNTIME_DIR is required for an XRDP session}"display_id="${DISPLAY#:}"display_id="${display_id//[^A-Za-z0-9_.-]/_}"if [ ! -d "$runtime_dir" ] || [ ! -w "$runtime_dir" ]; then    echo "XRDP runtime directory is not writable: $runtime_dir" >&2    exit 1fiumask 077keyring_dir="$(mktemp -d "$runtime_dir/keyring-rdp-${display_id:-unknown}-XXXXXX")"export GNOME_KEYRING_CONTROL="$keyring_dir"gnome-keyring-daemon \    --start \    --components=secrets \    --control-directory="$keyring_dir" \    >/dev/nullexec startxfce4

设置权限：

bash
1
sudo chmod 755 /usr/local/bin/xrdp-xfce-session

包装脚本根据当前 Display 创建权限为 700 的临时 Keyring 控制目录。每次启动使用唯一目录，避免重新连接或多个远程会话相互删除仍在使用的控制目录。

最终启动链路为：

text
1
2
3
4
5
6
7
8
9
10
11
xrdp-sesman  ↓/etc/xrdp/startwm.sh  ├── 读取 /etc/profile 与 ~/.profile  ├── 清除已有图形会话环境  └── dbus-run-session        ├── 创建 RDP 私有 Session Bus        └── xrdp-xfce-session              ├── 创建独立 Keyring 控制目录              ├── 启动 Secret Service              └── 启动 Xfce

3.5 配置 Fcitx5

由于新的 startwm.sh 绕过了 Debian /etc/X11/Xsession，不能再假设 ~/.xprofile 会被自动读取。本文明确读取 ~/.profile，所以将输入法环境变量写入该文件：

sh
1
2
3
4
5
# Fcitx5 input methodexport GTK_IM_MODULE=fcitxexport QT_IM_MODULE=fcitxexport XMODIFIERS=@im=fcitxexport GLFW_IM_MODULE=ibus

这里只负责设置环境，不要直接在 .profile 中启动 fcitx5。创建 ~/.config/autostart/fcitx5.desktop，让 daemon 在当前 Xfce 会话中启动：

ini
1
2
3
4
5
6
7
8
[Desktop Entry]Type=ApplicationName=Fcitx 5Comment=Start Fcitx 5 Input MethodExec=fcitx5 -dTerminal=falseHidden=falseX-GNOME-Autostart-enabled=true

职责划分为：

text
1
2
3
4
5
~/.profile  └── 设置输入法环境变量Xfce Autostart  └── 在当前图形会话中启动 fcitx5 daemon

im-config -m 中出现 Active configuration: missing (normally missing) 不一定表示配置错误。在自动模式下，只要当前选择和自动选择均为 fcitx5，就无需为了消除 missing 强制生成 ~/.xinputrc。

3.6 检查 PAM Keyring 配置

检查 /etc/pam.d/xrdp-sesman：

bash
1
grep -n 'pam_gnome_keyring' /etc/pam.d/xrdp-sesman

Debian 软件包通常已经提供类似配置：

text
1
2
-auth    optional  pam_gnome_keyring.so-session optional  pam_gnome_keyring.so auto_start

如果已经存在，不要重复添加。PAM 认证发生在 startwm.sh 创建私有 D-Bus 之前，因此 PAM 启动的 Keyring 仍不能代替包装脚本中服务于远程私有 bus 的 Secret Service。

四、使用公开脚本自动配置

4.1 执行 XRDP 模块

手工配置有助于理解启动链路，实际部署时可以直接使用公开的 homelab-setup。克隆项目后执行：

bash
1
2
3
git clone https://github.com/DoraTiger/homelab-setup.gitcd homelab-setupbash init.sh --silent 12-xrdp.sh

对应实现位于：

• modules/12-xrdp.sh：安装依赖并编排配置流程；
• lib/xrdp-config.sh：生成和收敛配置的纯函数；
• tests/integration/test-xrdp-config.sh：验证幂等性、D-Bus 隔离、Keyring 和 Fcitx5 环境。

4.2 脚本的收敛策略

脚本按配置归属分别处理这些文件：

• 只修改 sesman.ini 的目标键，保留其他 section 和用户配置；
• 已经具备正确私有 D-Bus 启动链的 startwm.sh 保留原内容，只校正权限；
• 修改系统文件前集中备份，不在 /etc 和用户目录中散落多个 .bak；
• Fcitx5 环境已经完整时保持用户文件不变；
• 只迁移内容与旧版脚本完全一致的 .xsession 和已知旧 polkit 规则；
• 用户自行维护的同名文件只提示，不自动删除；
• 配置完成后不会主动重启正在运行的 XRDP 服务，避免中断现有会话。

这部分设计主要解决“脚本能重复运行”和“不能覆盖用户已有配置”两个问题。相关集成测试会在临时目录中连续执行两次配置收敛，确保结果保持一致。

4.3 重新建立远程会话

配置完成后，应在方便时正常注销当前远程 Xfce，然后重启服务：

bash
1
sudo systemctl restart xrdp xrdp-sesman

只关闭 RDP 客户端窗口通常是断开连接，不代表远程 session 已经注销。为了确保新的 startwm.sh、D-Bus 和 Keyring 启动链完整生效，首次验证时应从 Xfce 菜单正常注销后重新登录。

五、验证会话隔离与桌面功能

5.1 验证 logind session

保持本地桌面登录，再使用同一个用户建立 RDP 连接。查看整机 session：

bash
1
loginctl list-sessions

然后分别检查本地和远程 session：

bash
1
2
3
4
5
loginctl show-session LOCAL_SESSION_ID \  -p Name -p Type -p Class -p Remote -p Seat -p Display -p Stateloginctl show-session RDP_SESSION_ID \  -p Name -p Type -p Class -p Remote -p Seat -p Display -p State

预期核心结果为：

text
1
2
本地：Display=:0   Remote=no   State=activeRDP： Display=:10  Remote=yes  State=active

loginctl list-sessions 查询的是整台机器的 systemd-logind 数据库，所以在本地和远程终端看到相同列表属于正常现象。

5.2 验证 DISPLAY 与 D-Bus

分别在两个桌面中执行：

bash
1
2
3
echo "DISPLAY=$DISPLAY"echo "DBUS_SESSION_BUS_ADDRESS=$DBUS_SESSION_BUS_ADDRESS"echo "XDG_SESSION_ID=$XDG_SESSION_ID"

典型结果如下：

重点不是 session 编号必须与示例一致，而是两个桌面的 Display、Session ID 和 D-Bus 地址不同，并且都处于 active 状态。

5.3 验证中文输入

在远程桌面执行：

bash
1
2
3
4
5
6
echo "$GTK_IM_MODULE"echo "$QT_IM_MODULE"echo "$XMODIFIERS"echo "$GLFW_IM_MODULE"pgrep -a fcitx5im-config -m

然后分别在本地和远程打开一个 GTK 编辑器，使用 Ctrl+Space 切换并输入中文。只有环境变量正确但没有 fcitx5 进程时，应检查 ~/.config/autostart/fcitx5.desktop，而不是继续修改 Locale。

5.4 验证 Secret Service

确认远程桌面仍使用私有 D-Bus：

bash
1
2
echo "$DBUS_SESSION_BUS_ADDRESS"busctl --user list | grep -E 'secret|keyring'

正常情况下，org.freedesktop.secrets 应显示实际 owner 和 PID，而不只是 (activatable)。

使用 secret-tool 完成读写测试：

bash
1
2
3
4
5
secret-tool store \  --label='XRDP Persistence Test' \  test persistencesecret-tool lookup test persistence

正常注销并重新建立远程会话后，再次执行 lookup。如果仍能读取保存的内容，说明新的 Keyring daemon 已经从 ~/.local/share/keyrings/ 加载持久化数据。测试完成后清理：

bash
1
secret-tool clear test persistence

最后启动 VS Code，确认不再提示 OS Keyring 不可用，GitHub Copilot OAuth 可以调用当前远程会话中的浏览器，并且重新登录 RDP 后凭据仍然存在。

六、问题排查

6.1 按启动层级检查日志

如果输入密码后仍然黑屏退出，不要同时修改多个参数。先确认软件版本、sesman.ini 和实际启动脚本：

bash
1
2
3
4
cat /etc/debian_versiondpkg -l | grep -E 'xrdp|xorgxrdp|xfce4-session'cat /etc/xrdp/startwm.shgrep -v '^[[:space:]]*[#;]' /etc/xrdp/sesman.ini

然后查看 XRDP 日志：

bash
1
2
sudo tail -200 /var/log/xrdp.logsudo tail -200 /var/log/xrdp-sesman.log

如果认证成功、远程 Xorg 已经启动并运行到 xfce4-session，继续排查桌面与 D-Bus：

bash
1
2
3
4
5
6
7
sudo journalctl -b --no-pager \  | grep -Ei 'xrdp|xfce|dbus|session|pam_systemd' \  | tail -250grep -RiE 'error|failed|already|session|dbus|display' \  ~/.xsession-errors* ~/.local/share/xrdp/ 2>/dev/null \  | tail -200

最后检查进程和会话：

bash
1
2
ps -u "$USER" -f | grep -E 'xfce|dbus|keyring|fcitx|xrdp|Xorg'loginctl list-sessions

6.2 几个容易误判的方向

只反复修改 ~/.xsession：它只负责选择桌面，不能隔离第二个 Xfce session。

把显卡警告直接当成根因：日志中可能出现 unsupported render node、amdgpu_device_initialize failed 等警告。如果远程 Xorg 已经建立并运行到 xfce4-session，这些警告通常不是本次退出的直接原因。

让 RDP 强制复用 /run/user/UID/bus：这样可能暂时让应用找到本地 Keyring，却会破坏远程桌面的 D-Bus 隔离。实测中会进一步影响浏览器和 OAuth 调用。

为了 im-config 的 missing 强制生成配置：应先确认自动选择是否已经是 fcitx5，不要只根据一个状态词判断输入法故障。

直接清理整个 Keyring 目录：多个会话可能仍在使用各自的控制目录。当前脚本使用 mktemp 创建唯一目录，不会为了新会话删除旧会话的目录。

七、适用边界

7.1 两个桌面仍然共享 $HOME

隔离 X11、D-Bus 和 Keyring 控制目录，并不等于把整个用户运行环境完全隔离。两个桌面仍然共享：

• 用户文件和配置；
• 浏览器 profile；
• ~/.local/share/keyrings/ 中的持久化数据；
• 使用文件锁或单实例机制的应用状态。

因此 Firefox、Chromium 等应用不适合在两个桌面中同时使用同一个 profile，某些托盘程序和单实例 GUI 软件也可能发生冲突。对于终端、IDE、文件管理和一般服务器运维，这种模式基本够用。

7.2 会话保留与资源占用

本文配置会保留断开的远程 session，并关闭空闲超时。这样可以在网络中断后重新连接原桌面，但也意味着长期不注销的 session 会持续占用内存和进程资源。完成工作后应从 Xfce 菜单正常注销，不要只关闭 RDP 客户端。

如果服务器需要严格的资源回收策略，应根据实际使用方式调整 KillDisconnected、DisconnectedTimeLimit 和 IdleTimeLimit，而不是直接沿用本文的长期保留配置。

八、总结

同一个用户无法同时运行本地和远程 Xfce，表面上表现为 RDP 黑屏退出，实际根因并不在密码、端口或 Display 编号，而是第二个桌面没有形成完整的会话隔离。

最终方案的核心是：

text
1
2
3
4
5
6
7
8
9
本地 Xfce :0  └── systemd User Bus + 本地 KeyringRDP Xfce :10  └── dbus-run-session        ├── 私有 D-Bus Session Bus        ├── RDP 专用 Secret Service        ├── Fcitx5        └── Xfce

调整后，本地与远程桌面可以同时保持 active，远程桌面中的中文输入、VS Code Keyring 和 Copilot 登录也能够正常工作，可以保留本地自动登录了。

相关实现已经进入公开的 homelab-setup，手工配置用于解释工作原理，日常部署则由脚本负责幂等收敛、备份和验证。后续如果 xrdp 或桌面环境版本发生变化，仍应以完整启动链和实际日志为依据重新验证，而不是只依赖某一条历史配置。

参考

• homelab-setup
• XRDP 配置模块
• XRDP 配置辅助函数
• XRDP 配置集成测试
• xrdp 官方项目
• dbus-run-session 文档
• GNOME Keyring 项目

知识管理是 Homelab 的核心用途之一。Obsidian 是基于 Markdown 的笔记工具，之前在 Obsidan 日记、记账与自动同步 中记录了 Windows 下的完整配置，包括 Templater 模板、Dataview 数据查询、Remotely Save 同步等。Zotero 则是文献管理工具，支持论文收集、标注和引用，是学术工作流的核心组件。两个工具配合使用，前者管理日常笔记和知识图谱，后者管理文献和引用，形成完整的个人知识管理体系。

现在需要在 Debian 服务器上也部署这两个工具，为后续与本地大模型、RAGFlow 等智能体服务对接打下基础。本文聚焦于 Linux 下的官方安装方式和基础 CLI 使用，插件配置和模板设置不再赘述。

一、Obsidian 安装

1.1 安装方式

Obsidian 官方提供 AppImage、Snap、Deb、Flatpak 四种 Linux 安装方式。考虑到 Debian 系统的兼容性和包管理的一致性，选择官方提供的 Deb 包进行安装。

bash
1
2
3
4
5
6
7
8
# 下载官方 Deb 包wget https://github.com/obsidianmd/obsidian-releases/releases/download/v1.12.7/obsidian_1.12.7_amd64.deb# 安装sudo dpkg -i obsidian_1.12.7_amd64.deb# 修复依赖（如果有缺失）sudo apt install -f

注意：版本号可能会更新，安装前请前往 Obsidian 下载页面 确认最新版本。

1.2 CLI 激活

Obsidian 的 CLI 默认未启用。首次安装后需要在 Obsidian 图形界面中激活：设置 → 通用 → 命令行接口，点击启用并按照提示将 CLI 链接到系统 PATH（Linux 下会链接到 ~/.local/bin/obsidian）。

注意：CLI 启用后需要重启终端才能生效。

1.3 基础 CLI 使用

Obsidian CLI 是一个功能完整的命令行工具，支持子命令模式操作。在 SSH 远程场景下尤其有用，可以直接在终端中管理笔记库，无需依赖图形界面。

bash
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
# 查看版本obsidian version# 列出已知的 vaultobsidian vaults# 查看当前 vault 信息obsidian vault# 打开今天的日记obsidian daily# 搜索笔记obsidian search query="关键词"# 创建新笔记obsidian create name="笔记标题" content="初始内容"# 读取当前文件obsidian read# 列出所有标签及使用次数obsidian tags counts# 在日记末尾追加内容obsidian daily:append content="- [ ] 待办事项"

Obsidian CLI 还支持插件管理（obsidian plugins）、主题管理（obsidian themes）、文件历史（obsidian history）等功能，完整命令列表可通过 obsidian help 查看。在远程桌面或 SSH 场景下，CLI 方式比图形界面启动更灵活，也可以配合 cron 或 systemd 实现自动化笔记操作。

1.4 Vault 同步方案

在 Homelab 场景下，Obsidian 的笔记同步可以通过以下方式实现：

原文中使用的 Remotely Save 插件基于坚果云 WebDAV 的方案在 Linux 上同样适用。如果追求去中心化和更快的同步速度，推荐后续部署 Syncthing。

二、Zotero 安装

2.1 安装方式

Zotero 官方 Linux 安装方式为下载编译好的 tarball。官方不提供 .deb 包，社区维护的 zotero-deb 虽然推荐用于 Debian 系统，但不在官方支持范围内。按照 官方安装文档 指引，选择 Official Tarball 方式安装。

与 Obsidian 不同，Zotero 的 tarball 安装不需要 sudo 权限。安装到用户目录 ~/.local/opt/zotero 即可，和 Node.js（fnm）、Go 等用户级工具保持一致的安装模式。

1. 前往 Zotero 下载页面 下载 Linux 64-bit 版本（当前为 Zotero 9）。

   bash
   1
   2
   # 下载 Zotero tarball（当前格式为 .tar.xz，版本号以实际页面为准）wget https://download.zotero.org/client/release/9.0.4/Zotero-9.0.4_linux-x86_64.tar.xz

2. 解压并将目录移动到用户目录。

   bash
   1
   2
   3
   4
   5
   # 解压tar -xJf Zotero-9.0.4_linux-x86_64.tar.xz# 移动到用户目录（无需 sudo）mv Zotero_linux_x86_64 ~/.local/opt/zotero

3. 运行 set_launcher_icon 脚本更新 .desktop 文件中的图标路径（.desktop 文件要求绝对路径）。

   bash
   1
   2
   cd ~/.local/opt/zotero./set_launcher_icon

4. 创建符号链接到 ~/.local/share/applications/，使其出现在应用启动器中。

   bash
   1
   ln -s ~/.local/opt/zotero/zotero.desktop ~/.local/share/applications/zotero.desktop

5. 启动 Zotero。

   bash
   1
   ~/.local/opt/zotero/zotero

注意：Zotero 更新后可能需要重新运行 set_launcher_icon 脚本。如果启动器中图标消失，删除旧的符号链接、等待几秒后重建即可。

2.2 Zotero Connector 配置

在浏览器中安装 Zotero Connector 扩展后，可以实现一键保存网页文献到本地 Zotero 库。在 Homelab 服务器上，如果通过 XRDP 远程桌面使用浏览器，Connector 同样可以正常工作。配置步骤：

1. 在浏览器扩展商店搜索 Zotero Connector 并安装。
2. 首次使用时，Connector 会自动检测 Zotero 客户端运行状态。
3. 在 Zotero 设置中配置数据同步和文件同步（可选使用 WebDAV 自建同步服务）。

2.3 Zotero 数据目录

Zotero 默认将数据存储在用户目录下，建议将数据目录迁移到 /home 分区的独立位置，方便备份和管理：

bash
1
2
3
# 修改 Zotero 数据目录（在 Zotero 编辑 - 首选项 - 高级 - 文件和文件夹中设置）# 默认路径：~/Zotero# 建议路径：~/data/zotero

三、自动化安装脚本

上述手动安装步骤已整理为 Homelab 环境配置工具的模块脚本，支持一键安装和幂等性升级。这两个模块是 setup/ 仓库（homelab-setup）在Homelab 搭建手记（3）开发环境一键配置发布后新增的，编号为 14-obsidian 和 15-zotero。

3.1 使用方式

bash
1
2
3
4
5
6
# 通过 init.sh 执行（交互式菜单，会自动扫描 modules/ 下所有脚本）cd setup && bash init.sh# 直接执行单个模块bash setup/modules/14-obsidian.shbash setup/modules/15-zotero.sh

3.2 脚本特性

3.3 脚本实现要点

两个脚本都遵循 setup/ 仓库的模块规范（详见Homelab 搭建手记（3）开发环境一键配置）：

• 公共函数统一使用 common.sh 中的 ensure_sudo、log_info、run_with_optional_proxy 等
• 幂等性检查：已安装且版本一致则跳过，版本不同则自动升级
• 安装包缓存在 $CACHE_DIR/<tool>/，重复执行不重复下载
• Zotero 特殊处理：下载页面是 JS 动态渲染，版本号从页面内嵌的 JSON 数据中提取；下载链接通过重定向获取实际 tar.xz 地址（非 tar.bz2）；安装到用户目录无需 sudo

四、总结

本文记录了 Obsidian 和 Zotero 在 Debian 系统上的官方安装方式。两者都是知识管理的核心工具，Obsidian 专注于笔记和知识图谱，Zotero 专注于文献管理和引用。后续文章会继续搭建 Syncthing 同步方案，将 Windows 端和 Debian 端的笔记库打通。

参考

• Obsidian 下载页面
• Obsidian CLI 文档
• Zotero 安装文档
• Zotero 下载页面
• Homelab Setup 仓库
• Obsidan 日记、记账与自动同步

前几篇记录了硬件选购、系统安装和开发环境配置。环境搭好后，下一步是配置日常开发工具。本篇聚焦日常开发的核心工具链：VS Code（远程开发 IDE）、Claude Code 和 MiMo Code（AI 编程助手），以及 Zellij（终端复用器）。特别是 Zellij 的会话持久化能力，让 TUI 工具断连后依然保持运行。

• 20260621：新增「五、Git 管理工具」，介绍 GitHub CLI（gh）和 Gitea CLI（tea-cli）的安装与登录配置。

一、VS Code 安装与配置

1.1 安装

从官网下载 .deb 包，本地安装：

bash
1
2
3
4
5
6
# 下载（或从官网下载后上传到服务器）wget -O /tmp/vscode.deb "https://code.visualstudio.com/sha/download?build=stable&os=linux-deb-x64"# 安装sudo dpkg -i /tmp/vscode.debsudo apt-get install -f  # 修复依赖

1.2 XFCE 环境下的密钥管理问题

XFCE 桌面默认不启动 gnome-keyring 守护进程，导致 VS Code 等应用无法正常访问系统密钥环，无法登录账号和同步配置。需要手动启用 gnome-keyring 自启动。

1.3 配置 gnome-keyring 自启动

关键一步 — gnome-keyring 的自动启动配置文件默认只对 GNOME 和 Unity 桌面生效，需要把 XFCE 也加进去：

bash
1
sudo nano /etc/xdg/autostart/gnome-keyring-pkcs11.desktop

找到 OnlyShowIn= 这一行，在末尾加上 XFCE;（注意用分号隔开）：

text
1
OnlyShowIn=GNOME;Unity;XFCE;

1.4 VS Code 远程开发

配置好密钥管理后，VS Code 可以正常登录账号、同步配置。XFCE 桌面环境下有两种方式启用远程隧道：

方式一：GUI 启用（推荐）

在 VS Code 的账号菜单中选择 Turn on Remote Tunnel Access，登录 GitHub 或微软账号后自动启动隧道。国内环境下微软账号更稳定，推荐优先使用。启用后保持 VS Code 运行即可，从其他设备的浏览器或 VS Code 打开 vscode.dev 隧道 URL 即可远程连接。

方式二：CLI 启动

bash
1
code tunnel

适用于没有桌面环境或需要在后台持续运行的场景。命令会自动下载并启动 VS Code Server，生成 vscode.dev 隧道 URL，其他设备直接通过浏览器或 VS Code 连接即可。

二、Claude Code

2.1 安装

Claude Code 已切换到原生安装方式，不再依赖 Node.js：

bash
1
2
3
4
5
# Linux/macOS 原生安装（推荐）curl -fsSL https://claude.ai/install.sh | bash# 或通过 claude 命令安装claude install

验证安装：

bash
1
claude --version

2.2 API 配置

Claude Code 支持多种 API 提供商，通过 ~/.claude/settings.json 配置：

json
1
2
3
4
5
6
7
{  "env": {    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",    "ANTHROPIC_AUTH_TOKEN": "your-api-key",    "ANTHROPIC_MODEL": "claude-sonnet-4-20250514"  }}

也可以使用第三方兼容 API（DeepSeek、MiMo 等），只需修改 BASE_URL 和 AUTH_TOKEN。配置完成后重启终端生效。

2.3 推荐插件

安装 superpower 插件可以显著增强 Claude Code 的能力：

bash
1
claude install-skill superpower

这个插件提供了代码审查、测试生成、重构建议等高级功能。

三、MiMo Code

3.1 MiMo Code 是什么

MiMo Code 是小米 MiMo 团队基于 OpenCode 构建的独立开源终端 AI 编程助手（MIT 协议），支持代码读写、命令执行、Git 管理等核心功能。可以接入 MiMo V2.5、DeepSeek 等多种模型。

3.2 安装

bash
1
2
3
4
5
# Mac/Linux（推荐）curl -fsSL https://mimo.xiaomi.com/install | bash# Windowsnpm install -g @mimo-ai/cli

安装完成后运行 mimo 启动。

3.3 连接模型

首次运行自动引导配置，或使用 /connect 命令连接模型提供商：

bash
1
2
3
mimo# 首次启动后执行/connect

支持接入多种模型：

• MiMo V2.5（免费，多模态，可识图看视频）
• DeepSeek 等第三方模型
• 登录后可使用更快的付费模型

3.4 使用建议

• 推荐常开 compose 模式：适合多步骤的复杂任务，可以自动拆分和执行
• 免费 MiMo V2.5：适合日常编程，速度较慢但零成本
• 付费模型：登录后使用，适合对响应速度有要求的场景

3.5 推广码

如果你也想体验 MiMo，可以使用我的邀请码注册，双方各得 ¥10 API 体验金 + 首单 9 折：

邀请码：67VNVN

注册地址：https://platform.xiaomimimo.com?ref=67VNVN

（注册后自动填入，体验金 40 天有效）

四、Zellij 终端复用器

4.1 为什么选 Zellij

Zellij 是一个现代的终端复用器，类似 tmux/screen，但设计更现代化。我选择它的核心原因是保证 TUI 工具的连续开发：

• Claude Code 和 MiMo Code 都是终端 TUI 工具，断开连接后进程会终止
• 在 Zellij 会话中运行它们，断开 SSH 后会话和里面的 TUI 继续在后台运行
• 重新连接后 zja 附加回去，Claude Code/MiMo Code 的上下文、文件状态全部保持

没有 Zellij，每次重连都要重新启动 AI 工具、重新加载上下文，效率很低。

4.2 安装与配置

Zellij 已在搭建手记（3）中通过 setup 脚本安装，配置文件在 ~/.config/zellij/config.kdl：

kdl
1
2
default_shell "bash"theme "dracula"

4.3 别名配置

为了快速操作，配置了几个常用别名：

bash
1
2
3
4
alias zj="zellij"                    # 快速启动alias zjl="zellij list-sessions"     # 列出所有会话alias zja="zellij attach"            # 附加到已有会话alias zjn="zellij -s"                # 新建命名会话

4.4 我的会话管理实践

我为不同的工作场景创建了固定的命名会话：

bash
1
2
3
4
5
6
7
8
# 创建会话（首次使用）zjn mimo          # MiMo Code 编程环境zjn claude        # Claude Code 编程环境zjn homelab       # Homelab 管理环境# 从其他设备连接zja mimo          # 附加到 MiMo 会话zja claude        # 附加到 Claude 会话

每次使用 zja mimo 就能立即回到上次的工作状态 — 打开的文件、运行的进程、终端布局全部保持不变。

4.5 Zellij 的多窗口调度

Zellij 的窗口管理比 tmux 更直观：

浮动窗格特别适合快速查看日志或执行临时命令，不需要打断当前工作流。

五、Git 管理工具

开发离不开代码托管平台。GitHub 和 Gitea 是目前最常用的两个平台，各自有对应的命令行工具：gh（GitHub CLI）和 tea-cli（Gitea CLI）。这两个工具可以完成大部分在网页端才能做的操作：创建仓库、管理 PR/Issue、查看 CI 状态等。

配置这两个工具的一个重要用途是让 AI 智能体（如 Claude Code、MiMo Code）能够自动化调用 Git 平台功能，实现从代码编写到仓库管理的全流程自动化。

5.1 GitHub CLI（gh）

安装

bash
1
2
3
4
# Debian/Ubuntucurl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpgecho "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/nullsudo apt update && sudo apt install gh -y

登录

gh 的登录流程非常简洁，会自动跳转浏览器完成授权：

bash
1
gh auth login

交互过程：

1. 选择账号：GitHub.com
2. 选择协议：SSH（推荐）或 HTTPS
3. 浏览器自动打开，显示 8 位授权码
4. 在浏览器中确认授权即可

登录完成后可以用 gh auth status 验证。

常用命令

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 克隆仓库gh repo clone owner/repo# 创建仓库gh repo create my-repo --public# 查看/创建 Issuegh issue listgh issue create --title "bug" --body "描述"# 管理 PRgh pr listgh pr create --title "feat" --body "改动说明"gh pr checkout 123# 查看 CI 状态gh run listgh run view 123

5.2 Gitea CLI（tea-cli）

安装

bash
1
sudo apt install tea-cli -y

注意命名差异：apt 安装的包名和命令都是 tea-cli，但执行 tea-cli help 后会发现帮助文档中自称 tea（这是上游项目原名）。apt search tea 出来的 tea 是另一个不相关的包，不要混淆。

登录

与 gh 不同，tea-cli 需要手动添加登录配置，且建议使用 Access Token 方式（用户名密码方式在某些 Gitea 实例上会失败）。

第一步：在 Gitea 网页端创建 Access Token

进入 Gitea → 用户设置 → Applications → 生成新的令牌：

• 令牌名称：随意填写（如 gitea-cli）
• 仓库和组织访问权限：选择「全部（公开、私有和受限）」
• 各项权限：全部选择「读写」

点击「生成令牌」后，立即复制保存，页面关闭后将无法再次查看。

第二步：通过 tea-cli 添加登录

bash
1
tea-cli login add

交互过程：

1. URL of Gitea instance: — 输入 Gitea 仓库地址（如 https://gitea.example.com）
2. Name for this login: — 输入别名（如 my-gitea）
3. Access token: — 粘贴刚才生成的 Token
4. Configure SSH key? — 输入 n（使用默认 SSH 密钥即可）
5. Skip TLS verification? — 输入 n（除非你的 Gitea 使用自签证书）

登录完成后用 tea-cli login ls 验证。

常用命令

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 查看登录列表tea-cli login ls# 设置默认登录tea-cli login default my-gitea# 查看仓库tea-cli repo ls# 创建仓库tea-cli repo create --name my-repo# 管理 Issuetea-cli issue lstea-cli issue create --title "bug" --body "描述"# 管理 PR（Gitea 称为 Pull Request）tea-cli pr lstea-cli pr create --title "feat" --body "改动说明"

5.3 两者对比

六、工具组合建议

这套工具组合覆盖了日常开发的核心场景：

七、总结

VS Code 负责远程开发和代码编辑，Claude Code 和 MiMo Code 代表了两种不同的 AI 编程路径 — 前者生态成熟，后者免费友好。Zellij 则保证了终端 TUI 工具的连续性，断连不中断。gh 和 tea-cli 分别打通了 GitHub 和 Gitea 的命令行工作流。这些工具组合使用，基本覆盖了从编码到部署的全流程。下一篇将继续 Homelab 系列，介绍容器与基础服务的部署。

参考

• Claude Code 官方文档
• MiMo 开放平台
• MiMo Code API 文档
• DeepSeek Claude Code 集成
• Zellij 官方文档
• Zellij GitHub
• GitHub CLI 官方文档
• Gitea CLI（tea）官方文档

前几篇记录了 DoraTiger 的功能实现。这篇补上平时维护主题时用到的命令、资源管理和发布流程，也记录一次子模块提交没有推送导致构建失败的问题。

一、CLI 命令

1.1 设计原则

清理、构建和更新资源都是维护主题时反复执行的操作，我把它们整理成了 CLI 命令，减少每次手动输入的步骤。

1.2 hexo themeinit

初始化主题配置文件，将默认配置复制到用户可编辑的位置：

javascript
1
2
3
4
5
6
7
8
9
10
11
// scripts/console/lib/themeinit.jsexports.handler = async function(args) {    const force = args.force || false;    const legacy = args.legacy || false;    if (exists(targetFile) && !force) {        log.info("配置文件已存在，跳过（使用 --force 覆盖）");        return;    }    // 复制默认配置到目标文件};

1.3 hexo algolia

上传文章索引到 Algolia，支持清空重建和预览模式：

javascript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// scripts/console/lib/algolia.jsexports.handler = async function(args) {    const client = algoliasearch(appId, apiKey);    const index = client.initIndex(indexName);    if (args.clean) await index.clearObjects();    if (args['dry-run']) { /* 仅预览不上传 */ }    const posts = hexo.locals.get('posts').toArray();    const records = posts.map(post => ({        objectID: post._id,        title: post.title,        content: post.content.substring(0, 5000),        tags: post.tags.map(t => t.name),    }));    await index.saveObjects(records);};

二、CI/CD 自动化

2.1 完整流程

目前的部署流程已经完全自动化：push 到 Gitea 后自动触发构建。

yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# .gitea/workflows/publish.yamlname: Generate and Deploy Hexo Siteon:  push:    branches: [main]    paths:      - "source/_posts/**"      - "themes/**"      - "_config.yml"      - "_config.*.yml"jobs:  generate-and-deploy:    runs-on: ubuntu-latest    steps:      - Checkout（含 submodules）      - 安装 Node.js + hexo-cli      - hexo clean && hexo generate      - hexo algolia（更新搜索索引）      - hexo deploy（SSH 推送到服务器）

触发条件精确到文件路径 — 只有文章、主题、配置文件变动才触发构建，避免无关提交浪费资源。

2.2 主题与博客的脱钩问题

这是实际使用中唯一遇到过的坑：主题修订后忘记 push，Gitea 拉取的远端版本还是旧的，导致构建出来的博客没有最新的主题改动。解决方法就是养成习惯：改完主题先 push 主题仓库，再 push 博客仓库（更新子模块引用）。

三、CDN 与本地资源管理

3.1 双轨设计的实际使用

之前在视觉系统篇介绍过 CDN + 本地的双重机制。实际开发中基本没有切换过 — 日常写博客都在本地环境，直接用本地资源；只有在服务器上构建时才可能用到 CDN。这个设计更多是为"万一"准备的，属于防御性设计。

yaml
1
2
3
4
resource:  enable_cdn: false        # 全局默认：本地  highlight:    enable_cdn: true       # 代码高亮强制 CDN（库体积大）

3.2 内置库清单

text
1
2
3
4
5
6
7
8
9
source/lib/├── highlight.js/@11.10.0/     # 代码高亮├── mathjax/@3.2.2/            # 数学渲染├── font-awesome/@6.7.2/       # 图标字体├── twikoo/@1.6.40/            # 评论系统├── valine/@1.5.3/             # 评论系统├── instantsearch.js/          # Algolia 搜索 UI├── pretext/                   # Canvas 文字排版└── prism.js/@1.29.0/          # 备用代码高亮

四、配置文档化

4.1 按功能整理配置说明

DoraTiger 的配置文档是我个人比较满意的部分 — 一种强迫症式的、划分明确的设计：

text
1
2
3
4
配置体系三层结构：  _config.yml（993 行）          ← 主题默认值，含所有配置项注释  docs/CONFIG.md（1051 行）      ← 完整配置说明，按功能分章节  _config.hexo-theme-doratiger.yml ← 用户覆盖文件，只写差异项

4.2 中英文双注释

每个配置项都采用中英文双注释，既方便中文用户理解，也方便国际用户参考：

yaml
1
2
3
4
5
6
7
# 是否开启 PV 统计# Whether to enable PV statisticsenable: true# 统计系统# Statistics system: busuanzi | countertype: "counter"

配置项旁边保留了中英文说明，修改配置时可以直接查看。

4.3 配置分区

配置文件按功能域分区，每个分区有清晰的边界注释：

yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# --------------------------------------------------# 样式配置# Style Configuration# --------------------------------------------------style:  color:    theme: "rgba(230, 119, 0, 1)"    # ...# --------------------------------------------------# 评论功能配置# Comment Function Configuration# --------------------------------------------------comment:  type: "twikoo"  # ...

每个功能的配置项集中在同一区域。新增配置时，同时更新旁边的注释和 docs/CONFIG.md 对应章节，避免两处说明不一致。

五、发布流程

5.1 发布检查清单

text
1
2
3
4
5
6
7
□ 版本号更新（package.json）□ CHANGELOG.md 更新□ README.md / README_en.md 同步□ 配置文档 docs/CONFIG.md 同步□ git commit + tag□ push 到 Gitea□ CI 自动构建 + 部署

5.2 发布后验证

bash
1
2
3
4
5
# 确认部署成功curl -s https://www.superheaoz.top/ | head -5# 确认子模块指针正确cd themes/hexo-theme-doratiger && git log --oneline -1

六、系列回顾

以上整理了这一阶段从博客搭建到主题开发的记录。主题还会继续修改，后续改动另写文章记录。

参考

• DoraTiger 主题 GitHub
• Hexo 官方文档
• Gitea Actions 文档
• Algolia 搜索服务

博客文章多了以后，查找旧内容主要依靠搜索。DoraTiger 保留了 Algolia 和本地搜索两种方式，这篇先记录它们的实现，再整理界面文字的多语言配置，以及评论系统的选型和停用原因。

一、搜索系统

1.1 从 Fan 到 DoraTiger 的搜索演进

搜索功能的演进和主题本身的历史紧密相关。最早在 Fan 主题上就遇到过 Algolia 适配出问题的情况 — 那也是我给 Fan 贡献代码的原因之一。后来在 DoraTiger 重构时，彻底升级了 Algolia 依赖版本（从 instantsearch.js v2 升级到 v4），基于新 API 全面重写了搜索模块。

本地搜索（local-search）用于不依赖外部服务的场景。Algolia 配额用完或服务不可用时，还可以使用站点生成的本地索引。

1.2 Algolia 搜索

bash
1
2
# 构建时上传索引npx hexo algolia

pug
1
2
3
4
5
6
7
8
// layout/_include/header/algolia.pug// instantsearch.js v4 + algoliasearch liteconst search = instantsearch({    indexName: '#{algoliaConfig.index_id}',    searchClient: algoliasearch('#{algoliaConfig.app_id}', '#{algoliaConfig.api_key}'),});search.addWidget(instantsearch.widgets.searchBox({ container: '#search-box' }));search.addWidget(instantsearch.widgets.hits({ container: '#hits' }));

1.3 搜索框的适配

搜索框的 UI 适配花了不少功夫。主要挑战是搜索结果列表需要在不同内容宽度下正确显示 — 文章标题过长时截断、搜索高亮文字不溢出、分页控件在窄屏下折叠。

stylus
1
2
// source/css/_layout/search.styl — 100 行// source/css/_layout/algolia.styl — 92 行

两个样式文件加起来 192 行，覆盖了搜索框、搜索结果、高亮文字、分页、空状态等所有交互状态。

1.4 本地搜索

作为 Algolia 的备用方案，本地搜索完全在客户端运行：

javascript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// source/js/utils/localSearch.jsclass LocalSearch {    loadIndex() {        // 懒加载：首次搜索时才 fetch JSON 索引        fetch(indexPath)            .then(r => r.json())            .then(data => { this.index = data.items; this.state = "ready"; });    }    search(query) {        // 200ms 防抖 + 子串匹配        return this.index.filter(item => {            const text = [item.title, item.excerpt, item.content,                         ...item.tags, ...item.categories].join(" ").toLowerCase();            return text.includes(query.toLowerCase());        }).slice(0, this.perPage);    }    highlight(text, query) {        const regex = new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "ig");        return text.replace(regex, m => `<mark>${m}</mark>`);    }}

1.5 字段合并策略

yaml
1
2
3
4
5
6
search:  field_merge_strategy: merge  # merge（追加）| replace（替换）  fields:    - title    - content    - tags

merge 模式在默认字段基础上追加用户自定义字段，replace 模式完全替换。这个设计来自 hexo-generator-search 的思路，保留了扩展灵活性。

二、国际化（i18n）

2.1 一种强迫症式的设计偏好

国际化属于个人的一种强迫症式习惯 — 喜欢这种可配置化、可扩展的方案设计。Hexo 本身支持 i18n，有相关文档，所以积极引入。虽然博客主要是中文，但 i18n 体系让主题具备了国际化能力，未来如果有需要可以直接扩展。

2.2 语言文件结构

yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# languages/zh-Hans.ymlhome:  read_more: "阅读全文"archives:  count:    zero: "暂无文章"           # _p() 复数：零    other: "目前共计 %d 篇文章"  # _p() 复数：其他footer:  statistics:    site_uv: "本站总访客数 {} 人"   # JS 运行时插值    page_pv: "本文总访问量 {} 次"copy:  success: "复制成功"  error: "复制错误"

2.3 三种占位符

2.4 覆盖范围

导航菜单、页面标题、文章元信息（创建时间/更新时间）、版权模板、复制按钮状态、搜索占位符和空结果提示、评论占位符、重定向提示、统计格式字符串等，都放在语言文件中，通过 _p() 或 __() 引用。

2.5 双语日志

javascript
1
2
3
4
5
6
// scripts/utils/log.jsfunction logInfo(key, ...args) {    const lang = hexo.theme.i18n.languages[0];    const msg = lang.startsWith('zh') ? zhMessages[key] : enMessages[key];    console.log(msg, ...args);}

三、评论系统

3.1 选型与继承

评论系统继承自 Fan 主题的架构，支持 Twikoo、Valine、Gitment 三种。选择 Twikoo 的原因是看到其他站点在用，感觉好用就尝试往里加了。

3.2 动态注入

javascript
1
2
3
4
5
6
7
// scripts/injectors/lib/injector-comments.jsswitch (commentType) {    case "twikoo":        return `<script>new Twikoo({ envId: '${envId}' })</script>`;    case "valine":        return `<script>new Valine({ appId: '${appId}' })</script>`;}

3.3 为什么关闭了评论

目前评论系统是关闭状态。原因是网站备案是个人网页性质，没有交互属性，索性就关了。

之前还考虑过一个更复杂的方案 — 结合 GitHub Pages 做双栈部署，国外 IP 访问路由到 Pages 上并开启评论功能。但最后嫌麻烦放弃了。

四、总结

目前搜索保留两种实现，界面文字集中在语言文件中。评论功能虽然保留在主题里，但我的博客因合规原因关闭了评论，没有继续部署两套评论服务。

参考

• Algolia InstantSearch
• Twikoo 评论系统
• hexo-generator-search
• hexo-algolia
• Hexo 国际化文档

文章加密、外链跳转和 SEO 最早都是通过第三方插件实现的。重构主题时，我把它们移到了内部，方便与页面模板一起调整。下面记录 AES-256-GCM 加密、外链拦截，以及 Sitemap、Robots.txt 和 JSON-LD 的生成方式。

一、文章加密

1.1 为什么需要加密

加密功能最初也是用的第三方插件（hexo-blog-encrypt），重构时一体化集成到主题内部。原因是加密功能和文章渲染管线耦合很深 — 加密后的文章需要特殊的渲染流程（先解密再渲染），第三方插件的实现和主题的渲染管线配合起来有各种边界问题。

目前只加密了一篇文章 — 本科同学录。属于私密内容，不适合公开。

1.2 加密方案

采用构建时加密 + 运行时解密的方案，无需后端服务：

text
1
2
3
4
5
6
构建时（Node.js 服务端）：  明文内容 → PBKDF2 密钥派生（100K 迭代）→ AES-256-GCM 加密  → 加密数据 + Salt + IV + Auth Tag 嵌入 HTML data 属性运行时（浏览器 Web Crypto API）：  用户输入密码 → PBKDF2 派生相同密钥 → AES-GCM 解密 → 显示内容

1.3 构建端加密

javascript
1
2
3
4
5
6
7
8
9
10
// scripts/filters/lib/encrypt.jsfunction encryptContent(content, password) {    const salt = crypto.randomBytes(16);       // 16 字节随机盐值    const iv = crypto.randomBytes(12);          // 12 字节随机 IV    const key = crypto.pbkdf2Sync(              // PBKDF2 派生密钥        password, salt, 100000, 32, "sha256"    // 100K 迭代，SHA-256    );    const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);    // ... 加密 + 提取 auth tag}

1.4 运行时解密

javascript
1
2
3
4
5
6
7
8
9
10
11
// 内联在 footer.pug 中async function decrypt(pwd) {    var keyMat = await crypto.subtle.importKey('raw', ...);    var key = await crypto.subtle.deriveKey({        name: 'PBKDF2', salt, iterations: 100000, hash: 'SHA-256'    }, keyMat, ...);    var pt = await crypto.subtle.decrypt({        name: 'AES-GCM', iv, tagLength: 128    }, key, combined);    return new TextDecoder().decode(pt);}

1.5 使用方式

yaml
1
2
3
4
# front-matterpassword: "my-secret-password"abstract: "本文已加密，请输入密码查看"   # 可选，覆盖默认提示message: "请输入密码"                     # 可选，覆盖默认按钮文字

加密后对搜索引擎的影响：加密页面的内容对爬虫不可见，不会被收录。对于私密内容这正是期望的效果。

二、外链重定向拦截

2.1 从公安备案到外链安全

这个功能的由来有一个小故事。博客最初只做了 ICP 备案，后来接到公安电话通知需要做公安备案。备案完成后，自然就考虑到了外链安全性的问题 — 如果博客上的链接指向了恶意网站，作为站长是有责任的。

最早是利用 Yourls 短链服务做的外链跳转 — 每个外链先转成短链，用户点击时经过 Yourls 中间页。有一段时间 Hexo 的提交记录全是改链接的，把旧的直接链接替换成短链格式（顺便说一下，这也催生了那篇 服务器操作指北（6）Yourls 短链接服务部署）。

但后来觉得每次加外链都得去 Yourls 后台手动加一条记录，太麻烦了。就像图片之前用七牛云 CDN，最后也是嫌麻烦放弃了。所以参考知乎的外链跳转风格，构建了一个主题自用的方案 — 构建时自动识别外链，运行时通过中间页拦截。同时因为做了 网站公安备案小记，外链安全性也成了必须考虑的问题。

2.2 构建时注入

javascript
1
2
3
4
5
6
7
8
9
10
// scripts/filters/lib/redirect.jsdata.content = data.content.replace(    /<a\s+([^>]*?)href=["']([^"']+)["']([^>]*)>/gi,    (match, pre, url, post) => {        if (!shouldRedirect(url)) return match;        return `<a ... class="external-link"             data-redirect="${encodeURIComponent(url)}"             target="_blank" ...>`;    });

2.3 运行时拦截

pug
1
2
3
4
5
6
7
8
9
// layout/_include/_layout.pugscript.    document.addEventListener('click', (e) => {        const link = e.target.closest('a[data-redirect]');        if (link) {            e.preventDefault();            window.open('/redirect/?url=' + link.dataset.redirect);        }    });

2.4 配置

yaml
1
2
3
4
5
redirect:  method: exclude          # exclude（默认）| include  exclude:    - "superheaoz.top"     # 自己的域名不拦截    - "github.com"

三、原生 Sitemap 与 SEO

3.1 从插件到内置

Sitemap 和 Robots.txt 最初也是用的第三方插件（hexo-generator-sitemap），重构时一体化集成。原因是这两个生成器逻辑不复杂，但和主题的配置体系（theme-config()）结合后可以做到更精细的控制。

3.2 Sitemap 生成器

支持 XML、TXT 或两者同时输出，优先级和更新频率可通过配置调整：

javascript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// scripts/generators/lib/sitemap.jsmodule.exports = function (locals) {    const urls = [];    urls.push({ loc: siteUrl + "/", freq: "daily", priority: 1.0 });    locals.posts.sort("-date").forEach(post => {        urls.push({            loc: siteUrl + "/" + post.path,            freq: changefreq,            priority: 0.8,            lastmod: post.updated        });    });    if (format === "xml" || format === "both")        results.push({ path: "sitemap.xml", data: buildXml(urls) });    if (format === "txt" || format === "both")        results.push({ path: "sitemap.txt", data: buildTxt(urls) });};

3.3 SEO 实际效果

这个博客主要还是以学习为目的，没有专门做 SEO 优化。简单对接了百度、谷歌、微软的站长统计功能 — 提交了 sitemap，配置了 robots.txt，加了 JSON-LD 结构化数据。对搜索引擎收录有一定帮助，但没有做过系统的 SEO 策略分析。

3.4 JSON-LD 结构化数据

pug
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// layout/_include/head.pugif(is_post())    script(type="application/ld+json").        {            "@type": "Article",            "headline": "#{page.title}",            "author": { "@type": "Person", "name": "#{config.author}" },            "datePublished": "#{page.date}",            "dateModified": "#{page.updated}"        }else    script(type="application/ld+json").        {            "@type": "WebSite",            "name": "#{config.title}",            "url": "#{config.url}"        }

四、总结

这些功能现在随主题一起维护。加密需要配合文章渲染，外链跳转需要处理页面中的链接，Sitemap 和结构化数据则使用站点与文章元信息。调整模板或渲染流程时，也要检查这些输出是否仍然正确。

参考

• Web Crypto API
• Schema.org Article
• Google 结构化数据测试
• robots.txt 规范

主题的文章页需要处理代码复制、目录和外链，列表页则涉及分页、归档与统计。这篇按这些功能记录实现过程，其中复制按钮的对齐和加密文章的目录适配，来回调整了比较多次。

一、文章渲染管线

1.1 渲染流程

文章从 Markdown 到最终页面经过多个处理阶段：

text
1
2
3
4
5
6
7
Hexo 解析 Markdown  → after_post_render 过滤器链    → code.js：代码块增强（行号 + 复制按钮 + 语言标签）    → redirect.js：外链重定向注入 data-redirect 属性    → encrypt.js：文章 AES-256-GCM 加密（可选）  → Pug 模板渲染    → post.pug：标题 / 元信息 / 内容 / 版权 / QR码 / 评论

1.2 代码块过滤器

将 <pre><code> 块增强为带语言标签、行号和复制按钮的容器：

javascript
1
2
3
4
5
6
7
8
9
10
// scripts/filters/lib/code.jsconst reg = /<pre><code(.*?)>([\s\S]*?)<\/code><\/pre>/g;data.content = data.content.replace(reg, (match, attrs, content) => {    const lang = attrs.match(/class="language-(.*?)"/)?.[1] || "code";    const codeHeader = `<div class="code-header">        <span class="code-type">${lang}</span>        <div class="code-copy">${copyButton}</div>    </div>`;    // ... 行号生成});

1.3 复制按钮的 UI 调试

复制按钮本身逻辑不复杂，但对齐代码块的 UI 花了不少功夫。最初想做一个带动效的花哨设计 — 点击时有个旋转/缩放反馈，hover 时有渐变背景。来来回回调整了好几版 DOM 结构和 CSS 动画，最后发现效果反而不稳定，在不同代码块宽度下对齐经常出问题。

最终放弃了花里胡哨的 DOM 方案，改用纯 JS 实现 — 直接操作 classList 和 textContent，不依赖复杂的 CSS 动画。效果虽然朴素，但稳定性好得多，各种代码块宽度下都能正确对齐。

javascript
1
2
3
4
5
6
7
// 简化后的复制逻辑button.addEventListener('click', () => {    navigator.clipboard.writeText(codeContent).then(() => {        button.textContent = copiedText;        setTimeout(() => { button.textContent = copyText; }, 2000);    });});

1.4 外链重定向

构建时给外链添加 data-redirect 属性，运行时拦截点击：

javascript
1
2
3
4
5
6
7
8
// scripts/filters/lib/redirect.jsconst shouldRedirect = (url) => {    const host = new URL(url).hostname;    if (host === siteHostname) return false;  // 内链排除    if (method === "include") return hostMatches(host, include);    if (hostMatches(host, exclude)) return false;  // 黑名单排除    return true;};

支持两种模式：exclude（默认，所有外链重定向，黑名单除外）和 include（仅白名单域名重定向）。

二、侧边栏双面板

2.1 面板切换

pug
1
2
3
4
5
6
7
8
9
10
// layout/_include/sidebar.pug- let showToc = enableToc && is_post()if showToc  #sidebar-toc    != toc(page.content, {list_number: ...})  .sidebar-menu-item  // 切换按钮  #sidebar-info.hideelse  #sidebar-info  #sidebar-toc.hide

2.2 TOC 面板的反复适配

TOC 面板是调试次数最多的组件之一。它需要同时适配两个场景：

场景一：侧边栏折叠/展开

• 侧边栏宽度从 300px 切换到 0 时，TOC 内容需要重新排版
• 高嵌套目录（三级以上）在窄宽度下文字溢出

场景二：文章加密

• 加密文章的 page.content 在构建时被替换为密文
• toc() 函数无法从密文生成目录
• 需要在加密前单独提取目录结构

这两个场景反复调整了好多次。把目录逻辑放在主题内，修改时可以一起检查侧边栏样式和加密前的处理顺序，不用分头适配。

2.3 滚动高亮

javascript
1
2
3
4
5
6
7
8
9
10
11
12
13
// source/js/utils/scroll.js// 滚动时自动高亮当前章节updateActiveHeading() {    const headings = document.querySelectorAll('.toc-item a');    const scrollTop = contentWrapper.scrollTop;    // 找到当前视口顶部最近的标题    headings.forEach(link => {        const target = document.querySelector(link.getAttribute('href'));        if (target && target.offsetTop <= scrollTop + offset) {            link.parentElement.classList.add('toc-active');        }    });}

三、分页系统

3.1 首页分页

javascript
1
2
3
4
5
6
7
8
9
10
11
12
13
// scripts/generators/lib/index.jsconst pagination = require("hexo-pagination");module.exports = function (locals) {    const posts = locals.posts.sort(this.config.index_generator.order_by);    const stickyPosts = posts.data.sort((a, b) => (b.sticky || 0) - (a.sticky || 0));    return pagination(path, stickyPosts, {        format: 'page/%d/',        layout: ['index'],        perPage: this.config.index_generator.per_page,    });};

置顶文章通过 sticky 字段排序，确保始终显示在首页最前。

3.2 文章前后导航

非分页页面（文章页）使用上一篇/下一篇文章导航，带 border-animation 效果。

四、归档/标签/分类页面

4.1 Timeline 样式归档

pug
1
2
3
4
5
6
7
8
9
// 按年份分组，年份 = 大圆点，文章 = 小圆点，竖线连接each year in Object.keys(groupedPosts)  .archive-year    .archive-year-marker     // 大圆点    .archive-year-title= year  each post in groupedPosts[year]    .archive-post-item      .archive-post-marker  // 小圆点      a(href=url_for(post.path))= post.title

4.2 标签云

pug
1
2
3
.tagcloud  != tagcloud({min_font: 0.75, max_font: 2, amount: 100,               color: true, start_color: '#A4D8FA', end_color: '#0790E8'})

颜色从浅蓝渐变到深蓝，字号从 0.75rem 到 2rem。

五、内置 PV/UV 统计计数器

5.1 从卜算子到自建

统计功能的演进路径：

text
1
2
3
4
5
6
localStorage（最早）  → 不跨浏览器，换设备数据丢失  → 卜算子 busuanzi（第三方服务）    → 服务不稳定，经常挂掉  → 自建 counter 服务    → 完全可控，支持 PV + UV

卜算子不好用了，逼得只能自己写。这也是选择一体化集成的又一个原因 — 外部服务不可控，不如自己掌握。

5.2 前端 UUID + Cookie

pug
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// layout/_include/footer.pug — inline IIFE(function() {    function getVisitorId() {        var match = document.cookie.match(/dtc_uid=([^;]+)/);        if (match) return match[1];        var uid = crypto.randomUUID();        document.cookie = 'dtc_uid=' + uid + '; max-age=31536000; path=/; SameSite=Lax';        return uid;    }    var visitorId = getVisitorId();    fetch(api + '?page=' + encodeURIComponent(location.pathname) + '&uid=' + visitorId)        .then(r => r.json())        .then(d => {            sv.textContent = d.site_uv || d.site_pv || 0;            pv.textContent = d.page_uv || d.page_pv || 0;        });})();

5.3 后端 counter 服务

doratiger-counter 服务（GitHub 仓库）使用内存布隆过滤器做 UV 去重：

• PV：内存计数器，每 30 秒持久化到 SQLite
• Site UV：布隆过滤器（100 万容量，7 个哈希函数）
• Page UV：map[page]map[uid]struct{}
• 安全：Origin 白名单校验，只允许来自博客域名的请求

布隆过滤器的选择是因为它在内存占用和查询速度之间取得了很好的平衡 — 100 万容量只需要约 120KB 内存，远小于存储每个 uid 的 map。对于个人博客的访问量级别，误判率可以接受。

六、文章附加功能

6.1 阅读时间估算

pug
1
2
3
4
5
// layout/_include/post.pug- let wpm = theme.post_extend?.reading_time?.wpm ?? 300- let wordCount = page.content.replace(/<[^>]+>/g, '').replace(/\s+/g, '').length- let readMin = Math.max(1, Math.ceil(wordCount / wpm))span= wordCount + ' 字 · 约 ' + readMin + ' 分钟'

WPM 参数可配置（默认 300），但中英文混排的字数统计有局限 — 去除 HTML 标签后按字符数计算，中文和英文都算一个字符，实际上中文的阅读速度比英文慢不少。300 这个值是参考了一些博客的通用设定，实际体验下来偏差不大，够用。

6.2 文章 QR 码

自行实现了 ISO 18004 标准的 QR 码生成器（纯 JS，无外部依赖），渲染为 SVG data URL。选择自己实现的原因和其他本地化组件一样 — 不需要在主题编译阶段引入第三方包，让 node 依赖尽量少，做到自包含。

6.3 其他功能

类似的实现思路贯穿整个主题 — 很多插件功能都是参考学习后自行实现的，就是为了尽量减少第三方包的安装，保持主题的自包含性。

七、总结

复制按钮和目录的逻辑都不算复杂，实际调试却花了不少时间。前者要适应不同宽度的代码块，后者还要处理侧边栏折叠和文章加密。以后修改文章页时，这几种情况都需要重新检查。

参考

• Hexo 过滤器文档
• Web Crypto API
• 布隆过滤器
• ISO 18004 QR 码标准
• doratiger-counter 项目

上一篇整理了主题架构，这篇记录配色、背景动画和布局的实现。DoraTiger 最初沿用了 Fan 的暗色风格，后来逐步把颜色和尺寸提取成配置，也尝试用 Canvas 绘制星空和首页文字。

一、暗色主题设计语言

1.1 为什么是暗色主题

DoraTiger 的暗色主题继承自 Fan 主题 — Fan 本身就采用了星空背景，整体偏暗色风格。从 Fan 重构时延续了这个基调，一方面视觉上已经习惯了，另一方面星空背景确实很适合 Canvas 动画的发挥。

中间考虑过加一个亮色主题，但一直没想好亮色对应的背景该用什么。纯白太单调，渐变又容易和内容区域冲突，就搁置了。所以目前只有暗色方案。

1.2 颜色体系

所有颜色通过 theme-config() 从配置文件读取，支持运行时覆盖：

stylus
1
2
3
4
5
6
// source/css/_variable/variable.styl$color-theme = theme-config('style.color.theme', 'rgba(230, 119, 0, 1)');         // 强调色（橙）$color-sub-theme = theme-config('style.color.sub_theme', 'rgba(7, 144, 232, 1)'); // 辅助色（蓝）$color-text = theme-config('style.color.text', 'rgba(255, 255, 255, 1)');         // 主文字（白）$color-background = theme-config('style.color.background',  'radial-gradient(100% 100% at 70% 120%, rgba(33, 39, 80, 1) 10%, #020409 100%)');

配色方案同样继承自 Fan 主题 — 橙色强调 + 蓝色辅助的组合在暗色背景下辨识度很高，一直沿用至今。亮色方案因为没找到合适的背景搭配，所以配色也没有重新调整。

设计原则：

• 深蓝黑径向渐变背景，不是纯黑 — 径向渐变让视觉有纵深感
• 白色文字 + rgba 透明度控制层级 — 主文字 1.0，次要文字 0.6
• 橙色强调用于交互反馈（hover、激活态），蓝色辅助用于链接

1.3 毛玻璃效果

内容区域使用半透明白色背景，配合边框和阴影实现毛玻璃感：

stylus
1
2
$color-content-background = theme-config('style.color.content_background',  'rgba(255, 255, 255, 0.1)');

1.4 随机色板

自动生成 11 个颜色 class，用于社交链接圆点等动态着色场景：

stylus
1
2
3
4
5
$colors = #495057 #f03e3e #ae3ec9 #7048e8 #4263eb #1098ad          #0ca678 #37b24d #f59f00 #f76707 #6f42c1;for color, i in $colors {  .bg-color{i} { background: color; }}

二、Canvas 动画系统

2.1 星空背景

全屏 <canvas> 元素 #universe，通过 requestAnimationFrame 驱动三种粒子效果：

javascript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// source/js/layout/background.jsclass Background {    constructor() {        this.canva = document.getElementById("universe");        this.starDensity = 0.001; // 每像素星星密度        this.createUniverse();    }    createUniverse() {        // 三种星星：        // 1. 巨星：大尺寸，缓慢水平漂移        // 2. 彗星：快速对角线划过，带拖尾        // 3. 普通星：随机闪烁（opacity 变化）    }}

画布覆盖在所有内容之下（z-index: -1），不影响交互。星星数量根据屏幕尺寸动态计算（starDensity * width），保证不同设备上都有合适的粒子密度。

移动端的 Canvas 性能表现一般 — 粒子数量虽然会根据屏幕缩小，但在低端设备上仍然有掉帧。目前没有做更激进的降级处理（比如关闭动画），算是一个已知的体验短板。

2.2 Hero 文字渲染

首页顶部的标题和副标题使用 Canvas 渲染，配合 pretext 排版引擎做精确文字布局：

javascript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// source/js/layout/hero.jsclass Hero {    resize() {        const rect = this.canvas.parentElement.getBoundingClientRect();        this.width = rect.width;        // 根据容器宽度动态计算字体大小        const titleFontSize = Math.min(this.width / 10, 64);        // 使用 pretext 做精确排版（支持自动换行）        const prepared = prepareWithSegments(this.title, font);        const { lines } = layoutWithLines(prepared, maxWidth * dpr, lineHeight * dpr);    }    draw(progress) {        // 每行文字渐入动画（stagger + easeOutExpo）        const lineDelay = line.type === 'title' ? i * 0.08 : 0.4 + i * 0.06;        ctx.globalAlpha = eased;        ctx.translate(0, (1 - eased) * 20); // 滑入效果    }}

pretext 库是前一阵刷技术博客时偶然发现的，看着能做 Canvas 文字排版就随手加进来了，没有做太多调研。实际用下来基本能用，但在响应式布局上还有一些小 bug（比如侧边栏切换时文字居中计算不准确），目前还没完全修好。

2.3 404 页面

Canvas 绘制发光的 “404” 文字 + 浮动粒子，倒计时后自动跳转首页：

javascript
1
2
3
4
5
6
7
8
9
10
// source/js/layout/page404.jsclass Page404 {    draw() {        // 文字描边 + 发光效果        ctx.shadowColor = 'rgba(255, 255, 255, 0.5)';        ctx.shadowBlur = 20;        ctx.strokeText('404', ...);        // 浮动粒子    }}

三、响应式布局

3.1 为什么用 JS 而非媒体查询

最初考虑过媒体查询方案，但实际对比后选择了 JS 动态计算，原因有两个：

媒体查询的局限：断点是固定的（比如 768px、1024px），但实际布局中每个区域的可用宽度不同。header 的宽度不等于 sidebar 的宽度，用统一的断点无法精确控制每个区域的行为。

JS 的灵活性：通过 getBoundingClientRect() 获取实际可用宽度，可以精确到像素级别控制显示/隐藏。而且 JS 可以通过 hook 机制按需嵌入，媒体查询则需要在 CSS 中写死所有断点规则，维护成本更高。

javascript
1
2
3
4
5
6
7
// source/js/layout/header.jsfunction autoResizeHeaderRight() {    const containerWidth = headerWrapper.getBoundingClientRect().width;    // 空间不足时依次隐藏：搜索按钮 → 站点标题 → 时钟    if (containerWidth < 600) searchButton.style.display = 'none';    if (containerWidth < 400) titleElement.style.display = 'none';}

不过移动端的自适应效果一般 — 主要是因为之前开发 Spring Boot + Bootstrap 项目时习惯了容器化排版，对 flex 布局有一种天然的偏好，所以做了自适应。但移动端屏幕尺寸有限，很多在桌面端好看的效果在手机上效果平平，算是一个妥协。

3.2 侧边栏折叠

侧边栏通过 CSS class 切换控制显隐，配合 transition 实现平滑动画：

stylus
1
2
3
4
5
6
7
8
9
// CSS#sidebar-container  width $sidebar-width  transition $transition-delay  &.closed    width 0    min-width 0    visibility hidden

javascript
1
2
3
4
5
// JS — 切换时通知其他组件function toggleSidebar() {    sidebarContainer.classList.toggle("closed");    window.dispatchEvent(new Event('layoutchange'));}

layoutchange 事件让 Hero 等组件感知布局变化，重新计算尺寸。

3.3 Meta 项自动换行

文章列表中，日期、分类、标签等 meta 项在内容过多时自动换行：

stylus
1
2
3
4
5
.post-item-header-meta  display flex  flex-direction row  flex-wrap wrap        // 关键：内容超宽时换行  gap 0.25rem 0        // 行间垂直间距

四、可复用动画 Mixin

三个核心 Mixin 覆盖了大部分交互动画场景：

4.1 下划线展开

stylus
1
2
3
4
5
6
7
hover-underline($left = 0)  &:after    left $left; width 0; height 0.125rem    background $color-theme  &:hover    &:after      left 0; width 100%

下划线从指定位置展开到全宽，用于菜单项、链接等。

4.2 四边框动画

四个子元素 .line-top/right/bottom/left，hover 时从外部展开到完整边框。用于统计数字、友情链接等卡片。

4.3 光扫按钮

::before 伪元素实现光扫效果：

stylus
1
2
3
4
5
6
button-hover-effect()  &::before    left -100%    background linear-gradient(to left, rgba(255,255,255,0), rgba(255,255,255,0.5), rgba(255,255,255,0))  &:hover::before    left 100%; transition left 0.5s ease

CSS 的动画语法确实绕，尤其是 ::before/::after 伪元素配合 transition 的各种组合，踩了不少坑。最终真正熟练掌握的主要是 Stylus 的变量、Mixin 和函数体系，底层 CSS 动画还是在实践中慢慢摸索出来的。

五、设计令牌系统

所有视觉参数通过 theme-config() 从配置文件读取，用户可在 _config.hexo-theme-doratiger.yml 中覆盖：

最初写样式的时候，颜色值直接写在各个 .styl 文件里：post.styl 里写一个 rgba(230, 119, 0, 1)，sidebar.styl 里又写一个，header.styl 里再来一个。后来想让主题色可配置，才发现到处都要改，费了不少功夫把十几个文件里的颜色逐一换成 theme-config() 引用，集中到 _variable/variable.styl 中管理。

这意味着用户无需修改任何 Stylus 代码，只改配置文件就能调整整个主题的视觉风格。

六、总结

写这篇时，暗色方案已经能日常使用，亮色背景还没有想好。移动端的动画性能和布局效果一般，pretext 在侧边栏切换时也还有排版问题。这些地方仍需要继续调整。

参考

• Stylus 中文文档
• pretext Canvas 排版引擎
• MDN Canvas API
• CSS Flexbox 布局

前几篇记录了 Hexo 的基础用法，下面开始整理自己开发 DoraTiger 主题的过程。这一篇先说为什么从 Fan 迁移，以及主题的配置如何合并、脚本如何加载。

一、从贡献者到独立开发者

1.1 与 Fan 主题的渊源

我最初使用的是 Fan 主题，并且在 GitHub 上为其贡献过代码，算是 Fan 主题的贡献者之一。使用了相当长一段时间，整体体验不错。

但后来作者长期没有更新，而 Hexo 版本在不断迭代。随着 Hexo 7.x 的发布，一些 API 和行为发生了变化，Fan 主题逐渐出现了兼容性问题。加上我当时正好有空，想深入学习一下 Pug、Stylus、ES6 Modules 等前端技术，所以决定从头构建一个自己的主题。

1.2 为什么选择一体化集成

最终没有选择继续维护 Fan 的 fork，而是完全重写，主要考虑的是一体化集成的设计理念。Hexo 主题生态中有大量优秀的第三方插件（加密、搜索、sitemap、统计等），但在实际使用中，将这些功能分散在不同插件中会带来一些问题：

• 各插件的配置格式不统一，维护成本高
• 插件之间可能存在兼容性冲突
• 功能逻辑分散在多处，排查问题困难
• 升级 Hexo 版本时，需要逐个检查插件兼容性

我把这些常用功能集成到 DoraTiger 内部，统一处理配置和加载逻辑。相关实现的原始来源和引用链接保留在主题 README.md 中。

1.3 重写目标

• 一体化集成 — 加密、搜索、sitemap、统计、外链拦截等功能直接内置
• 暗色主题 + Canvas 动画
• 配置文档（docs/CONFIG.md）
• 模块化脚本架构，方便扩展

二、技术选型

2.1 模板引擎：Pug

Hexo 主题支持 Pug 和 EJS 两种模板引擎。选择 Pug 的原因：

• 缩进语法：嵌套结构一目了然，不需要成对的 <% %> 标签
• 原生支持：extends/block/include/mixin 等模板功能
• 与 Stylus 一致：同为简洁表达力强的设计哲学

pug
1
2
3
4
5
6
// Pug 示例：条件渲染 + 循环if is_post()  .post-item-header-meta    each tag in post.tags.data      .post-item-header-meta-item        a(href=url_for(tag.path))= tag.name

从 Fan 主题迁移到 Pug 的过程中，Hexo 版本升级没有遇到严重的不兼容问题。主要是一些小的加载逻辑 bug，比如模板继承顺序、变量作用域等，调试后都能解决。Pug 本身在 Hexo 各版本间保持了良好的向后兼容性。

2.2 样式预处理：Stylus

Stylus 的缩进语法与 Pug 一致，支持变量、Mixin、函数，适合构建设计令牌系统：

stylus
1
2
3
4
// 设计令牌：所有值通过 theme-config() 从配置文件读取$color-theme = theme-config('style.color.theme', 'rgba(230, 119, 0, 1)');$color-background = theme-config('style.color.background',  'radial-gradient(100% 100% at 70% 120%, rgba(33, 39, 80, 1) 10%, #020409 100%)');

2.3 客户端脚本：ES6 Modules

所有客户端脚本使用 ES6 Modules，浏览器原生支持，无需构建步骤：

javascript
1
2
3
4
5
6
7
8
9
10
11
12
// source/js/main.js — 入口文件import { initClock } from "./layout/header.js";import { initToggleSidebar } from "./layout/sidebar.js";import ScrollHandler from "./utils/scroll.js";import Background from "./layout/background.js";document.addEventListener("DOMContentLoaded", () => {    initClock();    initToggleSidebar();    new ScrollHandler();  // 有状态组件用 class    new Background();     // Canvas 动画});

两种初始化模式并存：无状态工具用 init*() 函数，有状态组件用 new Class() 实例化。

三、三层配置合并与加载调试

直接修改主题的 _config.yml，升级时需要处理自己的配置与上游改动。因此我把用户配置放在主仓库中，加载时再与主题默认值合并：

text
1
2
3
4
优先级（高 → 低）：  _config.hexo-theme-doratiger.yml  ← 用户覆盖（推荐）  source/_data/doratiger_config.yml ← 已废弃  themes/xxx/_config.yml            ← 主题默认（993 行）

3.1 合并实现

javascript
1
2
3
4
5
6
7
8
// scripts/events/lib/themeConfig.js — 核心合并逻辑themeMergeConfig = merge({}, defaultThemeConfig);           // 层 1：主题默认值if (isNotEmptyObject(dataThemeConfig)) {    themeMergeConfig = merge({}, themeMergeConfig, dataThemeConfig);  // 层 2：用户数据}if (isNotEmptyObject(rootThemeConfig)) {    themeMergeConfig = merge({}, themeMergeConfig, rootThemeConfig);  // 层 3：根目录覆盖（最高优先级）}

使用深度合并（deep merge），嵌套对象不会被整体替换，而是逐字段合并。

3.2 调试过程中的最大坑：配置加载时序

最初实现三层合并时遇到了一个很大的问题：多处配置的加载顺序不一致。Hexo 的生命周期中，配置在不同阶段被读取，但有些模块需要的环境变量在配置还没加载完的时候就被引用了。结果就是部分功能的配置项读不到值，表现为"配置写了但不生效"。

排查后发现根本原因是：Hexo 的 ready 事件、generateBefore 事件、模板渲染阶段各自读取配置的时机不同，如果没有统一的加载器，就很容易出现时序问题。

最终参考了其他主题的实现思路，完全自行构建了变量加载器，在 ready 事件中一次性完成所有配置的读取和合并，然后在 generateBefore 阶段统一写回。这样无论后续哪个模块读取配置，拿到的都是完整且正确的值。

text
1
2
3
4
5
6
修复前：  ready → 部分模块读配置 → generateBefore → 其他模块读配置（不一致）修复后：  ready → themeConfig.js 统一加载三层配置 → mergeConfig.js 一次性写回  generateBefore → 所有模块读到的配置一致

3.3 两步模式的优势

javascript
1
2
3
// scripts/events/lib/mergeConfig.jshexo.theme.config = merge({}, themeConfig, doratiger.config);hexo.theme.i18n.data = merge({}, themeI18nConfig.data, doratiger.i18n.data);

这种两步模式（themeConfig 收集 → mergeConfig 应用）将配置解析与 Hexo 内部生命周期解耦。配置的"计算"和"生效"分离，便于调试和扩展。

四、脚本注入架构

4.1 Hook 的生效机制

Hexo 的 injector 系统提供四个生命周期钩子：head_begin、head_end、body_begin、body_end。理解这些钩子的生效时机是正确注入内容的关键：

text
1
2
3
4
5
6
7
8
9
10
HTML 渲染顺序：  <head>    head_begin  ← 非常早期，DOM 还没构建    head_end    ← head 尾部，适合 CSS 和配置脚本  </head>  <body>    body_begin  ← body 开头    [页面内容]    body_end    ← body 尾部，适合 JS 和评论初始化  </body>

4.2 空 hook 的意义

DoraTiger 中有些 hook 当前是空的（如 head_begin），但仍然注册了默认内容。这是有意为之 — 为将来可能的功能预留注入点，避免后续添加功能时需要修改核心注入逻辑：

javascript
1
2
3
4
// scripts/injectors/index.js// 即使当前为空，也保持注册hexo.extend.injector.register("head_begin", () => {}, "default");hexo.extend.injector.register("body_begin", () => {}, "default");

4.3 实际注入内容

javascript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// head_end：注入 CSS + 搜索配置hexo.extend.injector.register("head_end", function () {    let inject_content = [];    inject_content.push(require("./lib/injector-config.js")(hexo));    inject_content.push(require("./lib/injector-search.js")(hexo));    inject_content.push(require("./lib/injector-resource.js")(hexo, "css"));    return inject_content.join("\n");}, "default");// body_end：注入 JS + 评论 + 统计hexo.extend.injector.register("body_end", () => {    let inject_content = [];    inject_content.push(require("./lib/injector-resource.js")(hexo, "js"));    inject_content.push(require("./lib/injector-resource.js")(hexo, "script"));    inject_content.push(require("./lib/injector-comments.js")(hexo));    return inject_content.join("\n");}, "default");

4.4 按功能开关加载资源

资源注入按功能开关控制 — 只有启用的功能才注入对应资源：

javascript
1
2
3
4
5
6
7
8
// scripts/injectors/lib/injector-resource.jsconst search = theme.search || {};if (search.enable && search_type) {    resources.push(loadResource(resource[search_type], resourceType, globalCDN));}if (statistics.enable) {    resources.push(loadResource(resource[statistics_type], resourceType, globalCDN));}

五、内置第三方库的设计决策

DoraTiger 将 highlight.js、mathjax、font-awesome 等第三方库内置在 source/lib/ 下，而非通过 CDN 引用。这个决策背后有两个实际原因：

国内网络问题：部分 CDN 在国内访问不稳定，jsDelivr 等偶尔会被限速或不可达。把库随站点一起提供，可以减少对这些外部地址的依赖。

内网开发需求：写博客时经常处于内网环境，没有外网连接。如果依赖 CDN，本地预览时样式和功能都会缺失。内置库让离线开发成为可能。

为此设计了本地 + CDN 双重机制，每个资源都可以独立切换：

yaml
1
2
3
4
5
6
resource:  enable_cdn: false        # 全局默认：本地  highlight:    enable_cdn: true       # 代码高亮强制 CDN（库体积大）  mathjax:    enable_cdn: false      # 数学渲染用本地（稳定性优先）

text
1
2
3
4
5
6
7
8
9
source/lib/ 内置库清单：├── highlight.js/@11.10.0/     # 代码高亮├── mathjax/@3.2.2/            # 数学渲染├── font-awesome/@6.7.2/       # 图标字体├── twikoo/@1.6.40/            # 评论系统├── valine/@1.5.3/             # 评论系统├── instantsearch.js/          # Algolia 搜索 UI├── pretext/                   # Canvas 文字排版└── prism.js/@1.29.0/          # 备用代码高亮

六、目录结构设计

text
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
themes/hexo-theme-doratiger/├── layout/                    # 模板层│   ├── *.pug                  # 页面模板（index/post/archive...）│   └── _include/              # 可复用组件│       ├── _layout.pug        # 主布局骨架│       ├── head.pug           # SEO/OG/JSON-LD│       ├── header.pug         # 导航栏│       ├── footer.pug         # 底栏 + 统计 + 备案│       └── sidebar.pug        # 侧边栏路由├── scripts/                   # 服务端脚本层│   ├── events/                # 生命周期钩子│   ├── filters/               # 内容过滤器│   ├── generators/            # 页面生成器│   ├── injectors/             # 资源注入器│   └── console/               # CLI 命令├── source/                    # 静态资源层│   ├── css/                   # Stylus 样式│   ├── js/                    # ES6 客户端脚本│   └── lib/                   # 内置第三方库└── languages/                 # i18n 翻译

关键设计决策：

七、总结

这部分开发中，花时间最多的是配置加载时序。配置写在文件里却没有生效时，需要检查读取发生在哪个阶段。统一加载器之后，加密、搜索和统计都从合并后的配置取值，排查起来方便了不少。第三方库则保留本地文件，方便在没有外网的环境下预览。

参考

• DoraTiger 主题 GitHub
• Hexo 主题开发文档
• Pug 模板引擎
• Stylus CSS 预处理器
• Fan 主题

前两篇分别介绍了 Hexo 的基础知识与插件生态。本文作为系列第三篇，聚焦官方文档中相对进阶但实用的功能模块：标签插件、数据文件夹、服务器配置、生成器原理和国际化支持。这些功能在日常博客维护和主题开发中经常用到，但容易被忽略。

一、标签插件

标签插件是 Hexo 内置的模板标签，可以在 Markdown 文章中直接使用，无需安装额外插件。它们的语法与普通 Markdown 不同，需要直接写在 Markdown 中（不能被 Markdown 语法包裹）。

1.1 引用块（blockquote）

用于添加引文，支持作者、来源、链接：

text
1
{% blockquote [作者[, 来源]] [链接] [链接标题] %}内容{% endblockquote %}

示例：

text
1
2
3
{% blockquote David Levithan, Wide Awake %}Do not just seek happiness for yourself. Seek happiness for all.{% endblockquote %}

1.2 代码块（codeblock）

比普通 ``` 代码块功能更丰富，支持标题、链接、行号高亮：

text
1
{% codeblock [标题] [lang:语言] [URL] [链接文字] [line_number:false] [mark:1,4-7] %}代码{% endcodeblock %}

也支持反引号语法：

text
1
2
3
``` [language] [title] [url] [link text]代码```

1.3 已废弃标签（Hexo 7.0+）

以下标签在 Hexo 7.0.0 中已移除，需使用 hexo-tag-embed 插件替代：

1.4 文章引用

在文章中引用其他文章，自动解析路径：

text
1
2
3
{% post_link 文章文件名 %}{% post_link 文章文件名 '自定义文字' %}{% post_link 文章文件名 '标题' false %}

这是系列文章间互相引用的常用方式。

1.4 资源引用

配合资源文件夹使用，引用文章的附件资源：

text
1
2
3
{% asset_img 图片名 %}{% asset_img 图片名 宽度 高度 %}{% asset_link 文件名 %}

1.5 其他标签

二、数据文件夹

Hexo 提供两种数据文件机制，用于在模板中使用自定义数据。

2.1 source/_data 目录

在 source/_data/ 下创建 YAML 或 JSON 文件，即可在模板中通过 site.data.文件名 访问：

yaml
1
2
3
4
# source/_data/menu.ymlHome: /Gallery: /gallery/Archives: /archives/

模板中使用（EJS / Pug 语法对照）：

ejs
1
2
3
<% for (var link in site.data.menu) { %>  <a href="<%= site.data.menu[link] %>"><%= link %></a><% } %>

pug
1
2
each link, name in site.data.menu  a(href=link)= name

典型用途：自定义导航菜单、友情链接列表、站点配置数据等。

2.2 资源文件夹（post_asset_folder）

在 _config.yml 中启用 post_asset_folder: true 后，每篇文章可以有同名的资源目录：

text
1
2
3
4
5
source/_posts/├── my-article.md└── my-article/    ├── image1.png    └── data.csv

文章中引用：

text
1
{% asset_img image1.png %}

三、服务器

3.1 基本使用

bash
1
2
3
4
5
npm install hexo-server --savehexo server          # 默认 http://localhost:4000hexo server -p 5000  # 指定端口hexo server -i 127.0.0.1  # 指定 IPhexo server -s       # 静态模式（不监视文件变动）

3.2 后台运行

hexo server 默认在前台运行，终端关闭后进程会被杀掉。需要后台持久运行时：

bash
1
2
3
4
5
# 脱离终端会话setsid hexo server -p 4000 > /tmp/hexo.log 2>&1 &# 或使用 nohupnohup hexo server -p 4000 > /tmp/hexo.log 2>&1 &

3.3 常用场景

3.4 静态模式与动态模式

• 动态模式（默认）：监视文件变动，修改 Markdown 后自动刷新
• 静态模式（-s）：只处理 public/ 目录，需要先 hexo generate，适合模拟生产环境

3.5 注意事项

• hexo server 的 0.0.0.0 监听在生产环境不安全，应通过 nginx 反代
• 静态模式下修改源文件后需要重新 hexo generate 才能生效
• 后台运行时建议使用 setsid 而非 nohup，以完全脱离终端会话

四、生成器

Hexo 的生成器（Generator）负责将 source/ 目录中的文件转换为 public/ 目录中的静态文件。理解生成器的工作原理，有助于排查构建问题和开发自定义功能。

4.1 内置生成器

4.2 自定义生成器

插件可以注册自定义生成器，通过 hexo.extend.generator.register 注册：

javascript
1
2
3
4
5
6
7
hexo.extend.generator.register('my-generator', function(locals) {  return {    path: 'output-file.html',    data: locals,    layout: 'my-layout'  };});

实际项目中常用的分页生成器借助 hexo-pagination 模块：

javascript
1
2
3
4
5
6
7
8
9
10
const pagination = require("hexo-pagination");module.exports = function (locals) {  const posts = locals.posts.sort(this.config.index_generator.order_by);  return pagination('', posts, {    format: 'page/%d/',    layout: ['index'],    perPage: this.config.index_generator.per_page,  });};

例如我的 DoraTiger 主题就自建了 11 个生成器（sitemap、robots、404、about、tags、categories、redirect、terms、privacy、local-search、index），替代了多个第三方插件。这些生成器在 scripts/generators/lib/ 下独立实现，通过 scripts/generators/index.js 统一注册。

4.3 数据流

text
1
source/ → Generator → data 对象 → Layout 模板 → public/

Generator 接收 locals（全站数据），输出 {path, data, layout} 对象，Hexo 根据 layout 查找对应的模板文件进行渲染。

五、国际化（i18n）

5.1 语言文件

在 languages/ 目录下创建语言文件：

text
1
2
3
4
languages/├── zh-Hans.yml    # 简体中文├── zh-Hant.yml    # 繁体中文└── en.yml         # 英文

文件内容为键值对：

yaml
1
2
3
4
5
# languages/zh-Hans.ymlpost.created: 创建于post.modified: 更新于post.untitled: 无标题home.read_more: 阅读更多

5.2 模板中使用

pug
1
2
3
4
5
// Pug 模板span= _p("post.created") + " " + date(post.date)// EJS 模板<span><%= _p("post.created") %> <%= date(post.date) %></span>

5.3 语言检测

根据 _config.yml 中的 language 设置自动选择：

yaml
1
2
# _config.ymllanguage: zh-Hans

Hexo 会优先查找精确匹配（zh-Hans.yml），找不到则回退到默认语言。

六、总结

本文补充了 Hexo 官方文档中相对进阶但实用的功能模块。标签插件让文章排版更灵活，数据文件夹支持模板数据复用，服务器配置影响开发体验，生成器是 Hexo 构建的核心机制，国际化则为多语言站点提供基础。下一篇将进入自建主题的实战开发。

参考

• Hexo 官方文档
• Hexo 标签插件
• Hexo 数据文件
• Hexo 服务器
• Hexo 模版

前两篇记录了迷你主机的选购和 Debian 系统的安装。系统装好后，接下来面临的问题是：如何快速配置完整的开发环境？之前在 WSL 下每次重装都要手动装 Go、Java、Node.js，还要配各种镜像源，流程繁琐且容易遗漏。这次决定把所有配置脚本化，形成一套可重复执行的 setup 工具，一键完成环境部署。本文记录整个配置体系的设计和实现过程。

• 20260621：01-apt-sources 模块新增 chrony 时间同步服务安装，解决新装系统时间未校准导致 SSL 证书验证失败等问题。

一、设计思路

1.1 核心原则

配置脚本的设计遵循几条基本原则：

• 幂等性 — 每个脚本可反复执行，已安装的跳过、配置相同的跳过，不会产生覆盖或冗余
• 缓存统一 — 包管理器缓存（apt、npm、pip、Go、Maven）统一放在 cache/ 目录下，重装系统不丢失
• 安装包归档 — 下载的安装包存放在 packages/ 目录，按软件分类，支持离线部署
• 国内镜像加速 — 所有包管理器统一配置清华/阿里云镜像，解决国内下载慢的问题
• 交互/静默双模式 — 支持交互式菜单选择执行，也支持 --silent 参数用于自动化部署

1.2 目录结构

text
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
workspace/├── setup/│   ├── common.sh          # 公共函数（日志、路径、交互工具）│   ├── init.sh            # 入口脚本（菜单/静默模式）│   ├── modules/           # 模块脚本，按编号顺序执行│   │   ├── 00-ssh.sh│   │   ├── 01-apt-sources.sh│   │   └── ...│   ├── keys/              # SSH 公钥目录│   └── README.md          # 完整文档├── cache/                 # 运行时缓存│   ├── go/│   ├── maven/│   └── npm/└── packages/              # 安装包离线归档    ├── golang/    ├── miniconda/    ├── texlive/    └── zellij/

二、使用方式

2.1 快速开始

bash
1
2
3
4
5
6
7
8
9
10
# 克隆仓库mkdir -p "$HOME/workspace"git clone https://github.com/DoraTiger/homelab-setup.git "$HOME/workspace/setup"cd "$HOME/workspace/setup"# 交互式菜单bash init.sh# 静默执行全部bash init.sh --silent

默认数据工作区为 ~/workspace，可通过菜单中的 w、--workspace-root 参数或 HOMELAB_WORKSPACE_ROOT 环境变量修改。缓存和安装包默认放在工作区的 cache/、packages/ 中；备份和公钥目录分别位于当前 setup 仓库的 backup/、keys/，不随数据工作区切换。

2.2 交互式菜单

bash
1
bash init.sh

启动后显示路径信息和模块列表，输入编号选择执行。以下按默认目录示意，使用 ~ 代指用户主目录；实际菜单显示展开后的绝对路径，模块列表作了省略：

text
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  Homelab Debian + Xfce 环境配置━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  Setup:    ~/workspace/setup  工作区:   ~/workspace  缓存:     ~/workspace/cache  安装包:   ~/workspace/packages  备份:     ~/workspace/setup/backup  代理:     未配置  升级模式: 关闭━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  可用模块:  ────────────────────────────────────────────────    [ 0] 00-ssh.sh            SSH 密钥生成与 authorized_keys 配置    [ 1] 01-apt-sources.sh    APT 软件源配置    [ 2] 02-git-config.sh     Git 全局配置    ...    [13] 13-zellij.sh         Zellij 终端复用器安装  ────────────────────────────────────────────────    [a] 全部  [p] 代理  [u] 升级模式  [w] 工作区  [q] 退出

2.3 静默模式

bash
1
2
3
4
5
6
7
8
# 执行全部模块bash init.sh --silent# 执行指定模块（按编号）bash init.sh --silent 1 3# 使用代理bash init.sh --silent --proxy socks5://127.0.0.1:7890

2.3 代理配置

网络受限时可通过代理确保下载稳定。支持 http://、https://、socks5:// 格式。模块中的 wget/curl 下载会自动走代理。

三、模块详解

3.1 基础设施

3.2 容器与运行时

3.3 语言工具链

3.4 桌面与工具

四、技术细节

4.1 交互工具

common.sh 提供统一的交互函数，所有模块共享：

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 单选菜单type=$(prompt_choice "选择密钥类型:" "ed25519" "ed25519" "rsa-4096" "ecdsa")# 是/否确认if prompt_yesno "是否配置镜像源?" "y"; then ... fi# 文本输入name=$(prompt_input "用户名:" "$(whoami)")# 密码输入（隐藏回显）pass=$(prompt_secret "请输入密码")# 表格展示prompt_table "文件名|类型|说明" "id_ed25519.pub|ed25519|本机密钥"

静默模式下所有函数自动使用默认值，不阻塞等待输入。

4.2 幂等性设计

每个模块脚本遵循统一的幂等模式：

bash
1
2
3
4
5
6
7
8
9
10
11
# 检测是否已安装if [ -f "$INSTALL_DIR/bin/xxx" ]; then    log_success "xxx 已安装"    # 检测是否需要升级    log_info "检查升级..."    xxx upgrade 2>/dev/null || trueelse    # 执行安装    log_info "安装 xxx..."fi

4.3 环境变量管理

所有环境变量通过 .bashrc.d/ 目录管理，每个模块一个文件：

text
1
2
3
4
5
6
7
8
9
~/.bashrc.d/├── conda.sh       # Miniconda├── go.sh          # Go├── nodejs.sh      # fnm + Node.js├── perl.sh        # Perl local::lib├── rust.sh        # Rust├── sdkman.sh      # SDKMAN├── texlive.sh     # TeX Live└── zellij.sh      # Zellij 别名

.bashrc 中通过统一的加载器遍历执行：

bash
1
2
3
4
5
6
# Load environment snippetsif [ -d "$HOME/.bashrc.d" ]; then    for f in "$HOME"/.bashrc.d/*.sh; do        [ -f "$f" ] && . "$f"    donefi

4.4 镜像源汇总

五、总结

整套 setup 工具覆盖了从 SSH 密钥到桌面环境的全链路配置，14 个模块脚本按依赖优先级排序，支持交互式选择和静默批量执行。所有工具统一安装到 ~/.local/opt/，环境变量通过 .bashrc.d/ 管理，国内镜像源统一配置，重复执行安全无副作用。后续新增模块只需在 modules/ 下添加脚本，菜单自动识别。

本文涉及的所有脚本已开源在 homelab-setup 仓库中，欢迎 clone 使用和反馈。

参考

• homelab-setup GitHub
• 清华大学开源软件镜像站
• Docker CE 清华镜像
• SDKMAN 安装文档
• fnm GitHub
• TeX Live 清华镜像
• TeX Live 安装指南

上一篇记录了迷你主机的选购和 Debian 系统的安装过程。本篇是一个小的硬件更新：将原装的联发科 MT7921 无线网卡更换为 Intel AX210，同时记录更换后在 XRDP 远程桌面环境下遇到的 WiFi 扫描授权问题及解决方案。

一、更换无线网卡

1.1 为什么要换

联想来酷 Mini Pro 原装无线网卡是联发科 MT7921，网上普遍反映该网卡在 Linux 下存在偶发断连、休眠唤醒后无法恢复等稳定性问题。Intel AX210 是目前 Linux 兼容性最好的 WiFi 6E 网卡之一，iwlwifi 驱动由 Intel 官方维护，稳定性有保障。

1.2 更换过程中的散热细节

拆机后发现一个值得注意的设计细节：原装硬盘和网卡是叠叠乐放置的，NVMe 硬盘直接叠在无线网卡上方，两者之间没有额外的散热隔层。这种布局下硬盘的热量会直接传导到网卡，长时间运行可能影响网卡稳定性。

更换网卡的同时，建议将第一块硬盘挪到另一个 M.2 插槽位置，拉开两者距离，改善散热条件。如果两个插槽位置固定无法更换，也可以在硬盘和网卡之间加一层导热垫或铜片辅助散热。

1.3 AX210 基本信息

更换后通过 dmesg 确认驱动正常加载：

bash
1
dmesg | grep -i "iwlwifi\|ax210"

text
1
2
loaded firmware version ...Detected Intel(R) Wi-Fi 6 AX210 160MHz

日志中可能会出现 failed to load iwl-debug-yoyo.bin 的提示，这是可选的 debug firmware 缺失，不影响正常使用。

二、XRDP 环境下 WiFi 扫描授权问题

2.1 问题现象

更换 AX210 后，系统本地登录一切正常，但在 XRDP 远程桌面环境中出现以下问题：

• 点击 XFCE 右上角 NetworkManager 的无线网络图标时弹出授权窗口
• 提示：System policy prevents Wi-Fi scans
• 即使不输入密码，WiFi 网络实际上仍然能扫描出来
• 一段时间后会再次弹出授权窗口
• 某些情况下 XFCE GUI 会出现卡死，NetworkManager applet 无响应

本地物理登录则完全正常，不会出现任何授权提示。

2.2 问题排查

首先排除驱动问题：

• AX210 驱动工作正常
• firmware 已正确加载
• 未使用 iwd
• NetworkManager 服务运行正常

通过 loginctl 查看会话状态，发现了关键线索：

bash
1
loginctl

text
1
2
3
SESSION  UID USER    SEAT4        1000 tiger  seat0c6       1000 tiger  -

其中 seat0 表示本地物理桌面，- 表示远程 XRDP 会话。XRDP 远程会话不被 systemd-logind / polkit 视为本地 active session，因此 WiFi 扫描操作会触发额外的权限校验。

本质上这不是网卡驱动问题，而是 XRDP 会话的权限模型与本地会话不一致导致的。

2.3 为什么 MT7921 没有触发该问题

不同无线网卡驱动在 NetworkManager / polkit 权限路径上的行为并不完全一致。Intel AX210 的 iwlwifi 驱动对权限模型实现更加严格，因此更容易暴露 XRDP 会话的权限问题。简单来说：

• MT7921 的驱动在权限校验上更"宽松"
• AX210 的 iwlwifi 更符合标准权限模型

2.4 解决方案：添加 polkit 规则

创建 polkit 规则文件：

bash
1
sudo vim /etc/polkit-1/rules.d/50-networkmanager.rules

写入以下内容：

javascript
1
2
3
4
5
6
7
8
polkit.addRule(function(action, subject) {    if (        subject.isInGroup("sudo") &&        action.id.indexOf("org.freedesktop.NetworkManager") == 0    ) {        return polkit.Result.YES;    }});

该规则表示：允许 sudo 组用户直接执行 NetworkManager 相关操作，不再弹出 WiFi 扫描授权窗口。

重启相关服务使规则生效：

bash
1
2
sudo systemctl restart polkitsudo systemctl restart NetworkManager

重新登录 XRDP 即可。

2.5 结果

配置完成后：

• 不再出现 System policy prevents Wi-Fi scans 提示
• 无线网络扫描恢复正常
• XFCE 不再出现 GUI 假死
• 无需安装额外 GNOME 桌面组件
• 无需修改 AX210 驱动配置

三、补充说明

3.1 关于 policykit-1-gnome

很多资料会提到通过安装 policykit-1-gnome 来解决类似问题。需要注意的是，policykit-1-gnome 并不是完整的 GNOME 桌面，仅仅是一个 polkit authentication agent，不会安装 GNOME Shell，也不会破坏 XFCE 环境。不过本问题中仅通过 polkit rule 即可解决，无需额外安装。

3.2 关于 XRDP 与本地图形会话共存

如果系统同时存在本地自动登录的 XFCE 和 XRDP 远程的 XFCE，可能导致 DBus、polkit、NetworkManager applet 之间出现额外冲突。对于长期远程使用的 Homelab 主机，更建议：

• 关闭本地自动登录
• 使用单一 XRDP 图形会话

以减少桌面环境相关的问题。

参考

• Arch Wiki - NetworkManager
• Polkit Documentation

之前手上的开发环境分散在多台电脑上，每台设备都要单独配置 WSL、安装依赖、同步配置，维护成本很高。加上一直想在本地跑一些小模型做 AI Agent 相关的实验，所以决定搭建一台集中式的 Homelab 服务器，统一承载开发环境、推理服务和各种自托管应用。本文作为 Homelab 系列第一篇，主要记录迷你主机的选购过程、Linux 发行版的选择思路，以及 Debian 系统的安装流程。

一、迷你主机选购

1.1 背景

2026 年上半年，DDR5 内存和 NVMe 固态硬盘的价格持续上涨，32G 内存条的价格相比去年同期涨了不少。在这个背景下，直接组装一台 ITX 小主机的成本偏高，转而考虑品牌迷你主机。品牌迷你主机的优势在于出厂已经完成内存和硬盘的搭配，整体价格比自己单买配件组装要划算不少，而且 618 大促期间往往有比较好的价格。

1.2 选购标准

选购迷你主机主要关注以下几点：

1.3 最终选择

综合对比了几款热门迷你主机后，最终在淘宝 618 活动期间以 2499 元购入了联想来酷 Mini Pro，具体配置如下：

Ryzen 7 8745H 本质是 8845H 的略微降频版本，实际使用中性能差异不大，但价格更有优势。780M 核显虽然是集显，但 RDNA 3 架构的性能已经可以胜任一些轻量的推理任务。双 M.2 硬盘位是加分项，后续可以加装第二块硬盘做数据盘或 RAID。

二、Linux 发行版选择

2.1 为什么不用 Ubuntu

之前一直在用 Ubuntu，但这次决定换掉它，主要有以下原因：

1. snap 的问题：Ubuntu 从 20.04 开始强推 snap 包管理，很多系统组件（如 Firefox）被替换为 snap 版本。snap 启动慢、占用空间大、自动更新无法关闭，对于服务器场景来说不够可控。
2. Ubuntu 26 的方向：Ubuntu 26.04 的宣传方向继续向 snap 倾斜，甚至有传言系统核心组件进一步 snap 化，这让我不想继续跟进。
3. LTS 周期：Ubuntu LTS 的 5 年支持期（付费可延长至 10 年）虽然够用，但相比 Debian 的社区驱动模式，总觉得受制于 Canonical 的商业决策。

2.2 发行版对比