现在各大 Linux 发行版很多都变成 systemd 的形状了，连 Synology DSM 7 都开始用 systemd 了，可以说是 Learn once, operate anywhere。不过有时候还是要在 Mac 机器上部署一些服务，需要用到 launchd/launchctl。

本文以一个熟悉 systemd/systemctl 工具的运维视角，整理了常用的 launchd 相关命令备忘。（说实话我每次都会忘记怎么用，然后得去翻手册……而且网上有时候还会教你用 load/unload 子命令，这些其实都已经标记为过时了，有新的命令替代它们）

list 查看所有

launchctl list# 类比 systemctl list-units

status 查看状态

launchctl print gui/501/uploadserver# -> ~/Library/LaunchAgents/uploadserver.plistlaunchctl print system/com.openssh.sshd# -> /System/Library/LaunchDaemons/ssh.plist# 类比 systemctl status uploadserver.service# -> /etc/systemd/system/uploadserver.service

这里的 system/ gui/501/ 叫做 domain-target，com.openssh.sshd 和 uploadserver 叫做 service-name，合起来之后叫做 service-target。service-name 一般就是下面 .plist 配置文件中的 Label。

其中 system/ 顾名思义就是系统级的，system domain，需要 root 权限才能修改。而 gui/501/ user/501/ 则是用户级的 user domain，其中 501 就是用户 uid。gui/<uid>/ 和 login/<asid>/ 下的服务只有用户登录了才会运行。

通常来说需要 GUI 运行的放在 gui/<uid>/ 下面，不需要的放在其他下面。不过考虑到 macOS 作为桌面操作系统的特性，其实一股脑都放 gui 下面也没啥问题。

start 启动

launchctl bootstrap gui/501 ~/Library/LaunchAgents/uploadserver.plist# 或者系统级的服务，需要 sudo 运行sudo launchctl bootstrap system /Library/LaunchDaemons/com.example.plist# 类比 systemctl start uploadserver.service# 不需要 systemctl daemon-reload

如果 bootstrap 提示下面的报错，就说明很可能是服务器已经在运行了，或者服务被 disable 掉了：

Bootstrap failed: 5: Input/output errorTry re-running the command as root for richer errors.

stop 停止

launchctl bootout gui/501 ~/Library/LaunchAgents/uploadserver.plist# 或者系统级的服务，需要 sudo 运行sudo bootout bootstrap system /Library/LaunchDaemons/com.example.plist# 除了 .plist 文件路径，也可以用 label 指定launchctl bootout gui/501/uploadserver# 类比 systemctl stop uploadserver.service

如果 bootout 提示下面的报错，就说明很可能是服务本来就没有在运行：

Boot-out failed: 3: No such process

restart 重启

launchctl kickstart -k -p gui/501/uploadserver# service spawned with pid: 17247# 参数：# -k       如果服务已经在运行了，先杀死现有的进程再重启# -p       成功后输出进程的 PID# 类比 systemctl restart uploadserver.service

如果 kickstart 提示下面的报错，就说明服务没有 bootstrap：

Could not find service "uploadserver" in domain for user gui: 501

enable 开机启动

一般来说你的 .plist 里配置了 RunAtLoad 的话，bootstrap 了之后默认就是开机启动的，不需要再 enable 一遍。

不过你也可以通过 disable 主动关闭服务的开机启动，这个是否 enable 的状态是 launchd 自己维护的，不会更改 .plist 文件的内容。使用 disable 禁止开机启动之后，想要恢复开机启动就需要用 enable。

launchctl enable gui/501/uploadserver# 类比 systemctl enable uploadserver.service

disable 禁止开机启动

launchctl disable gui/501/uploadserver# 类比 systemctl disable uploadserver.service

config 配置文件

类似于 systemd 的 Unit File，以 .plist/XML 文件的形式存在：

~/Library/LaunchAgents   Per-user agents provided by the user./Library/LaunchAgents    Per-user agents provided by the administrator./Library/LaunchDaemons   System-wide daemons provided by the administrator./System/Library/LaunchAgents   Per-user agents provided by Apple./System/Library/LaunchDaemons  System-wide daemons provided by Apple.

通常来说我们只会用到前三个。Daemon 和 Agent 的区别：

• Daemon：系统级、单个实例服务多个用户、不应显示 UI、没有用户登录也会运行、可以以 root 权限运行。
• Agent：每个用户各自运行实例、直接与用户交互、用户不登录则不会运行、以普通用户权限运行。

这里以 ~/Library/LaunchAgents/uploadserver.plist 为例：

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict>    <key>KeepAlive</key>    <true/>    <key>Label</key>    <string>uploadserver</string>    <key>LimitLoadToSessionType</key>    <array>        <string>Aqua</string>        <string>Background</string>        <string>LoginWindow</string>        <string>StandardIO</string>        <string>System</string>    </array>    <key>ProcessType</key>    <string>Background</string>    <key>ProgramArguments</key>    <array>        <string>/opt/homebrew/bin/uvx</string>        <string>uploadserver</string>        <string>8888</string>        <string>-d</string>        <string>/tmp/upload</string>    </array>    <key>RunAtLoad</key>    <true/>    <key>EnvironmentVariables</key>    <dict>        <key>FOO</key>        <string>BAR</string>    </dict>    <key>StandardErrorPath</key>    <string>/tmp/uploadserver.log</string>    <key>StandardOutPath</key>    <string>/tmp/uploadserver.log</string>    <key>TimeOut</key>    <integer>5</integer></dict></plist>

类比 /etc/systemd/system/uploadserver.service：

[Unit]Description=Upload ServerWants=network-online.targetAfter=network-online.target[Service]ExecStart=/root/.local/bin/uvx uploadserver 8888 -d /tmp/uploadRestart=alwaysRestartSec=5Environment="FOO=BAR"StandardOutput=file:/tmp/uploadserver.logStandardError=file:/tmp/uploadserver.log[Install]WantedBy=multi-user.target

具体怎么写就不多说了，大部分开机自启 + 守护进程需求用上面的模板就够了，有其他需求的直接看文档。

名字基本可以随便取。另外注意有多个命令行参数的话，要拆成多个 <string>。

不再推荐使用的 Legacy 命令

现在很多教程里还在用 load/unload，不过在 macOS 10.11 之后，官方手册中已经不再推荐使用这些老的命令，应该使用上面的命令替代。

另外一点需要注意的是，load/unload 通过执行 launchctl 命令时的权限来决定 domain。如果使用 sudo launchctl 执行的，算作 system domain，否则算作 user domain。之前被坑过一次……💩

launchctl load ~/Library/LaunchAgents/uploadserver.plist# 应该替换为 launchctl bootstrap gui/501 ~/Library/LaunchAgents/uploadserver.plistlaunchctl load -w ~/Library/LaunchAgents/uploadserver.plist# 相当于先 enable 再 bootstraplaunchctl unload ~/Library/LaunchAgents/uploadserver.plist# 应该替换为 launchctl bootout gui/501 ~/Library/LaunchAgents/uploadserver.plistsudo launchctl load /Library/LaunchDaemons/com.example.plist# 应该替换为 sudo launchctl bootstrap system /Library/LaunchDaemons/com.example.plistsudo launchctl unload /Library/LaunchDaemons/com.example.plist# 应该替换为 sudo bootout bootstrap system /Library/LaunchDaemons/com.example.plist

可视化管理工具

推荐 Lingon X，有点像以前 Windows 上的那种开机进程管理，可以查看当前系统上有哪些 Agent/Deamon，以及它们的配置，挺方便的。

小尾巴

我记得以前 macOS 设置页面里的启动项管理很垃圾，只能显示部分启动项，但实际上程序想要开机自启有很多种方法：

• LoginItems (Helper App with SMLoginItemSetEnabled)
• LaunchAgents (~/Library/LaunchAgents or /Library/LaunchAgents)
• LaunchDaemons (/Library/LaunchDaemons)
• 直接拖动到设置页面「登录时打开」列表中

搞得有些流氓软件开机自启了你都不知道，比之 Windows 还不如。当时我还准备写篇博客，在不安装第三方清理软件的情况下如何删除这些启动项，但后来不了了之了。

不过好在后来的 macOS 更新把这块的管理补上了，现在在设置页面就可以直接管理上面那些方式添加的启动项，挺好。

使用成品 NAS，在相对省心的同时，也意味着更低的自由度。很多自定义操作都是在和这些定制化 OS 斗智斗勇。

本文介绍了在 QNAP 威联通 NAS（以及 Synology 群晖 NAS）上关闭 ssh 密码登录，仅允许密钥登录的方法。Synology 相对还好，对 OpenSSH 的魔改不多，和普通 Linux 一样修改 /etc/ssh/sshd_config 就好了。

但是 QNAP 这个 B，每次启动 sshd 服务都会重新生成配置，直接修改上述配置文件是没法持久化保存的。

风险提示

为了避免你被锁在门外，修改自带 sshd 配置之前，最好自己再起一个 ssh 服务，等确认 OK 了之后再关掉。以及最重要的，做好备份！

sudo opkg install dropbearsudo dropbear -F -p 9922 -P /opt/var/run/dropbear.pid -R -w -E

如果你不幸已经进不去系统了，可以这样自救（别问我为什么知道🤣）：

• 从 Web UI 打开 Container Station / Container Manager
• 通过上传 docker-compose.yml 的方式创建容器（通常方式创建的话是不让挂载特殊路径的）
• 挂载要修改的路径，比如 /etc/init.d/
• 启动容器后，选择 打开终端机/连接终端，然后把改坏的文件改回来

services:  rescue-tmp:    image: ubuntu:latest    container_name: rescue-tmp    stdin_open: true    tty: true    command: /bin/bash    volumes:      - /etc/init.d:/work

Synology NAS

⚠ 改文件之前做好备份！

执行 sudo vim /etc/ssh/sshd_config，修改：

 PubkeyAuthentication yes ChallengeResponseAuthentication no-PasswordAuthentication yes+PasswordAuthentication no

然后 sudo synosystemctl restart sshd.service 重启 sshd 生效，或者在 DSM Web UI 上关闭「启动 SSH 功能」后再打开也可以。

值得一提的是，直接修改 sshd_config 中的 Port，会导致 sshd 监听在两个端口上，一个是 Web UI 上设置的「SSH 端口」，一个是配置文件中配置的端口，而且后者是无法用于登录 Shell 的，会提示 Permission denied, please try again.。

研究了一下，应该是因为 sshd 被魔改过，会读取 /etc/synoinfo.conf 文件里的 ssh_port 配置。

sudo lsof -c sshd# COMMAND   PID USER  FD   TYPE  SIZE/OFF    NODE NAME# sshd    28232 root cwd    DIR      4096       2 /# sshd    28232 root rtd    DIR      4096       2 /# sshd    28232 root txt    REG    888480   20645 /usr/bin/sshd# sshd    28232 root   3u  IPv4       0t0     TCP *:2222 (LISTEN)# sshd    28232 root   4u  IPv6       0t0     TCP *:2222 (LISTEN)# sshd    28232 root   5u  IPv4       0t0     TCP *:6622 (LISTEN)# sshd    28232 root   6u  IPv6       0t0     TCP *:6622 (LISTEN)cat /etc/synoinfo.conf | grep -i port# ssh_port="2222"# sftpPort="3322"# rsync_sshd_port="4422"strings /usr/bin/sshd# SYNOServiceSSHPortGet# /etc/ssh/sshd_config# /etc/synoinfo.conf# Permission denied, please try again.

而根据 Reverse Engineering Synology’s OpenSSH 这篇博客里的说法，这个魔改过的 OpenSSH 会校验一些参数，所以无法连接。

不过对于我们的目标「禁用 ssh 密码登录」没什么影响，就这样吧。这些厂商定制化的东西还是少碰，别给整挂了。

QNAP NAS

大的来了（掩鼻）。

先看看 QNAP 的 sshd 用的什么配置文件：

ps aux | grep sshd# 22714 admin     11504 S   /usr/sbin/sshd -f /etc/config/ssh/sshd_config -p 2222cat /etc/config/ssh/sshd_config# Protocol 2# HostKey /etc/ssh/ssh_host_ed25519_key# PermitRootLogin yes# UseDNS no# Subsystem sftp /usr/libexec/sftp-server# AllowTcpForwarding yes# AllowUsers admin prinecho 'PasswordAuthentication no' | sudo tee -a /etc/config/ssh/sshd_config

重启 sshd 后，你会惊喜地发现，刚才改掉的配置文件，诶，又被改回来了😁：

sudo setsid /etc/init.d/login.sh restartgrep PasswordAuthentication /etc/config/ssh/sshd_config

既然配置文件没法持久化，那就只能从启动脚本下手了。

简单看看 /etc/init.d/login.sh（文件缩进就是这样，我保留了原汁原味）：

SSH=/usr/sbin/sshdSSHD_CONF=/etc/config/ssh/sshd_configSSHD_CONF_DEFAULT=/etc/ssh/sshd_configSSH_PORT=`/sbin/getcfg LOGIN "SSH Port" -d 22`update_sshd_config(){ /sbin/mksshdconf ENABLED_SFTP=`/sbin/getcfg LOGIN "SFTP Enable" -u -d TRUE` # ... #Set PermitRootLogin yes OPTION="PermitRootLogin" if [ -z "`grep .*${OPTION}.* ${SSHD_CONF}`" ]; then     echo "${OPTION} yes" > ${SSHD_CONF} else        sed -i "s/^#\s\?${OPTION}\s\?[yesno]\{1,3\}.*/${OPTION} yes/g" ${SSHD_CONF} fi # ...}# ...case "$1" in    start) # for openssh 7.5p1 and later sed -i '/^UsePrivilegeSeparation .*/d' ${SSHD_CONF_DEFAULT} /bin/chmod 0400 /etc/config/shadow* /etc/default_config/shadow update_ssh_client_config if [ `/sbin/getcfg LOGIN "SSH Enable" -u -d FALSE` != FALSE ]; then  echo -n "Starting sshd service: "  generte_ssh_key     if [ ! -f "${SSHD_CONF}" ]; then      /bin/cp -f ${SSHD_CONF_DEFAULT} ${SSHD_CONF}     fi     if [ ! -f "${SSHD_CONF}" ]; then      SSHD_CONF=${SSHD_CONF_DEFAULT}     fi  update_sshd_config        sshd_privilege_separation  /sbin/daemon_mgr sshd start "$SSH -f ${SSHD_CONF} -p $SSH_PORT"  echo "OK"  touch /var/lock/subsys/sshd fi ;; # ...esac

你可能以为有这个 cp -f ${SSHD_CONF_DEFAULT} ${SSHD_CONF}，我们就能通过修改 /etc/ssh/sshd_config 来实现配置持久化了 —— 天真！

实测下来发现 /sbin/mksshdconf 这个二进制每次执行都会重置 /etc/config/ssh/sshd_config 的内容，所以你 cp 了也没有用。我也不知道他们为什么要写一个没有意义的 cp 在那里。🤷

我搜了下，这篇博客 里也有类似的吐槽：

For reasons I can’t fathom, the SSH config on a QNAP seems nuts (If anyone knows why it works this way, please let me know, because I must be missing something obvious).

就算抛开这些不谈，你这个强制 PermitRootLogin yes 是何意啊？

所以我们还是只能改脚本，重启 sshd 后生效：

⚠ 改文件之前做好备份！

--- /etc/init.d/login.sh.bak+++ /etc/init.d/login.sh@@ -83,6 +83,9 @@ update_sshd_config() {  /sbin/mksshdconf+ echo 'PasswordAuthentication no' >> ${SSHD_CONF}+ echo 'ChallengeResponseAuthentication no' >> ${SSHD_CONF}+ sed -i "s/PermitRootLogin yes/PermitRootLogin no/g" ${SSHD_CONF}  ENABLED_SFTP=`/sbin/getcfg LOGIN "SFTP Enable" -u -d TRUE`  if [ "x${ENABLED_SFTP}" = "xTRUE" ]; then

注意：系统更新后这个脚本会被重置，需要重新修改。

Bonus: macOS

其实和大部分 Linux 一样啦，写在这里只是为了顺便记一下：

cat << EOF | sudo tee /etc/ssh/sshd_config.d/10-no-passwords.confPubkeyAuthentication yesPasswordAuthentication noKbdInteractiveAuthentication noEOF

sshd_config.d 里的序号规则是 小的覆盖大的。

重启 sshd：

# Linux systemdsystemctl restart ssh.servicesystemctl status ssh.service# macOS launchdlaunchctl kickstart -k -p system/com.openssh.sshdlaunchctl print system/com.openssh.sshd

让 VNC 远程桌面只能通过 ssh 隧道连接（仅监听 127.0.0.1）：

sudo defaults write /Library/Preferences/com.apple.RemoteManagement.plist VNCOnlyLocalConnections -bool yesssh -L 5900:127.0.0.1:5900 mac-mini

小尾巴

保不齐这些 NAS 系统后续更新会出什么幺蛾子，可以让 AI 搓一个脚本，放在 Docker 容器里 crontab 定时运行，然后给一个服务器列表，一旦发现任何服务器允许 PasswordAuthentication，就发送通知告警。

修改后的效果：

ssh -o PreferredAuthentications=password,keyboard-interactive prin@192.168.1.10 -p 2222# prin@192.168.1.10: Permission denied (publickey).ssh -o PreferredAuthentications=password,keyboard-interactive prin@192.168.2.10 -p 2222# prin@192.168.2.10: Permission denied (publickey).

我的主力 NAS 是 Synology 群晖 DS920+，陪了我也快 4 年了。DS920+ 出厂默认是不支持将 M.2 NVMe SSD 作为存储池的，只能作为缓存使用。后来出的 DS923+ 倒是支持创建 M.2 存储池了，但是只能用它自家的兼容性列表中的盘，也不知道套的哪家 OEM，贵得要死，买是不可能买的这辈子不可能买的。

好在有大神写了脚本 Synology_HDD_db，可以直接修改这个「兼容性列表」所在的数据库，把你在用的硬盘型号加进去。系统一读这个数据库发现型号在里面，就可以正常使用了。不过缺点是每次系统更新后，都需要重新执行一遍脚本。

今天看到关于 飞牛 fnOS 0day 漏洞 的帖子，寻思着也给 DS920+ 更新一下系统，毕竟一直都稳定运行着，也没有特意去升级。虽然我没用飞牛，也没有把服务暴露到公网，不过各家 NAS 系统的 CVE 其实都挺多的，以防万一嘛。

结果升级完系统 NAS 就开始疯狂嘀嘀嘀叫，才想起来还有硬盘兼容性这一茬……太久远了，顺手记录一下，免得下次再忘了。

报错界面是这样的：

• 当前发出哔声的原因：存储空间或 SSD 缓存异常
• 检测到不支持的硬盘（缓存设备 2）
• 在存储池 3 中检测到一个或多个硬盘缺失
• 严重 存储池 3 发生问题
• 缓存设备 2 - M.2 NVMe SSD 不受当前 DSM 版本支持

更新硬盘兼容性数据库

这个 M.2 存储池是 2023 年建的，记得当时好像还不需要捣鼓什么兼容性数据库，应该是后来 DSM 7 加上的。

总之就是运行一下 Synology_HDD_db 这个脚本，每次系统更新完都要跑一遍，然后重启设备生效。

# 版本号自己改成最新的wget https://github.com/007revad/Synology_HDD_db/archive/refs/tags/v3.6.119.zip7z x v3.6.119.zipcd Synology_HDD_db-3.6.119sudo -s ./syno_hdd_db.sh -nr --showedits# 用到的脚本参数：# -n, --noupdate        Prevent DSM updating the compatible drive databases# -r, --ram             Disable memory compatibility checking (DSM 7.x only)# -s, --showedits       Show edits made to <model>_host db and db.new file(s)

比如我这里用的就是一条致态的 2TB 作为下载盘，另一条 256GB 的作为 HDD 缓存。

脚本运行以后，就会把你目前插着的硬盘加到 NAS 本地的兼容性列表数据库里了。

ls -al /var/lib/disk-compatibility/ | grep ds920+_host_v7# -rw-r--r--  1 root root 156K Feb  1 02:07 ds920+_host_v7.db# -rw-r--r--  1 root root 148K Jan 19 17:11 ds920+_host_v7.db.bak# -rw-r--r--  1 root root  97K Oct 27  2023 ds920+_host_v7.db.new.bak# -rw-r--r--  1 root root    8 Jan 19 17:11 ds920+_host_v7.release# -rw-r--r--  1 root root    4 Jan 19 17:11 ds920+_host_v7.versioncat /var/lib/disk-compatibility/ds920+_host_v7.db | jq .

所谓数据库，其实就是个大 JSON：

{  "disk_compatbility_info": {    // ...    "ZHITAI TiPlus7100 2TB": {      "ZTA22002": {        "compatibility_interval": [          {            "compatibility": "support",            "not_yet_rolling_status": "support",            "fw_dsm_update_status_notify": false,            "barebone_installable": true,            "barebone_installable_v2": "auto",            "smart_test_ignore": false,            "smart_attr_ignore": false          }        ]      },      // ...    }  },  "nas_model": "ds920+"}

建立 M.2 SSD 存储池

如果是 DS923+，运行完上面的脚本之后应该直接在 DSM Web UI 上创建存储池就可以了。

DS920+ 还是得自己手搓，记录一下用到的命令（之前参考的是 这篇博客）：

# 查看当前的 NVMe 设备，找到你要的 SSDls -al /dev/nvme*sudo fdisk -l /dev/nvme0n1# 给 SSD 分区，有多块盘的话小心别弄错了sudo synopartition --part /dev/nvme0n1 12# 看看当前的 RAID 状态，如果已经有 md5 了就新建 md6cat /proc/mdstatsudo mdadm --create /dev/md6 --level=1 --raid-devices=1 --force /dev/nvme0n1p3# 创建文件系统sudo mkfs.btrfs -f /dev/md6sudo mdadm --detail /dev/md6sudo reboot

重启 NAS 后，检查一下：

sudo fdisk -l /dev/nvme0n1# Disk /dev/nvme0n1: 1.9 TiB, 2048408248320 bytes, 4000797360 sectors# Disk model: ZHITAI TiPlus7100 2TB# Units: sectors of 1 * 512 = 512 bytes# Sector size (logical/physical): 512 bytes / 512 bytes# I/O size (minimum/optimal): 512 bytes / 512 bytes# Disklabel type: dos# Disk identifier: 0xae2a9134# Device         Boot   Start        End    Sectors  Size Id Type# /dev/nvme0n1p1          256    4980735    4980480  2.4G fd Linux raid autodetect# /dev/nvme0n1p2      4980736    9175039    4194304    2G fd Linux raid autodetect# /dev/nvme0n1p3      9437184 4000795469 3991358286  1.9T fd Linux raid autodetectsudo mdadm --detail /dev/md6# /dev/md6:#         Version : 1.2#   Creation Time : Fri Jun  2 02:16:39 2023#      Raid Level : raid1#      Array Size : 1995678080 (1903.23 GiB 2043.57 GB)#   Used Dev Size : 1995678080 (1903.23 GiB 2043.57 GB)#    Raid Devices : 1#   Total Devices : 1#     Persistence : Superblock is persistent#     Update Time : Sun Feb  1 03:25:45 2026#           State : clean#  Active Devices : 1# Working Devices : 1#  Failed Devices : 0#   Spare Devices : 0#            Name : localhost:6  (local to host localhost)#            UUID : 2729425e:28782224:04f5d205:be6fcc6c#          Events : 45#     Number   Major   Minor   RaidDevice State#        0     259        3        0      active sync   /dev/nvme0n1p3

然后去 Web UI 的「存储管理器 > 存储空间 > 可用池」，点击「在线重组」就好了。

小尾巴

顺便吐槽一下，这系统升级完把我所有的容器都停了，也不给我自动重启，我还得一个一个过去 docker compose up -d 拉起来……

下次有空的话聊聊 HomeLab 的安全性问题：不仅仅是这次飞牛 fnOS 的路径穿越漏洞，还有之前影响到多个 self-hosted 软件乃至众多生产环境的 React Server Component RCE 漏洞，claude-relay-service 的鉴权绕过漏洞等等，都说明了把内网服务暴露到公网是极其危险的。很多人图方便喜欢搞什么内网穿透、DDNS、公网 IP、域名访问、DMZ、UPnP，殊不知距离被入侵可能只有一步之遥。

我有三台 NAS，Synology 群晖、QNAP 威联通和 ZSpace 极空间，前者放在出租屋里作为主力，后两台放在老家作为备份。

因为极空间是 arm64 版本双盘位的，功耗不高，所以和 QNAP 共用一台 UPS 就好了。之前折腾了一下，让极空间作为 Master 通过 USB 连接 UPS，然后 QNAP 作为 Slave 通过 NUT (Network UPS Tools) 局域网连接。

不过因为涉及到系统文件改动，每次极空间系统升级后都需要重新操作一遍，每次我都会忘记要怎么捣鼓……所以写篇博客记录下。

话说 2025 年居然一篇博客都没写，工作太忙了呀，而且总是犯懒。以前上学的时候写博客，不怎么理解那些断更的博主，现在可以体会到那种感觉了……草稿倒是堆了很多，希望明年可以发出来吧！

TL;DR

以 root 权限登录极空间，运行以下命令，然后重启服务即可。

sed -i 's/127.0.0.1/0.0.0.0/g' /zspace/applications/services/nut/config/upsd.confcat >> /zspace/applications/services/nut/config/upsd.users << EOF[admin]        password = 123456        upsmon slave        allowfrom = %EOFcat >> /zspace/applications/services/nut/config/ups.conf << EOF[qnapups]        driver = usbhid-ups        port = auto        desc = "zspace ups for qnap"        lowbatt = 15        pollfreq = 15        offdelay = 60EOF

备注

首先要吐槽的就是 QNAP 这个傻逼系统，我已经不知道吐槽过多少次了。

QNAP 的天才工程师的天才设计：在作为 Network UPS Slave 连接时，用户只能指定「网络 UPS 服务器的 IP 地址」这一个选项，剩下的都是写死的：

• 用户名 admin
• 密码 123456
• 端口 3493
• 名称 qnapups

只要任何一个不对都连不上。Man! What can I say?

所以如果你想让 QNAP 和极空间共享一台 UPS，有两个选择：

1. QNAP as Master，极空间 as Slave
2. 极空间 as Master，QNAP as Slave

不过当时 24 年我折腾的时候，极空间还不支持 NUT Slave 模式。虽然那会儿极空间已经开放了 ssh 和 root 权限（也是这家之前总是被吐槽的一点），但是考虑到如果通过修改系统文件的方式让极空间支持 NUT Slave，可能不稳，毕竟这种定制系统也不知道哪里改了些什么东西。

所以我选择的是极空间通过 USB 物理连接 UPS，启动 NUT Server 作为 Master，QNAP 作为 Slave 客户端连接 NUT Server。

UPS <---{USB Cable}---> ZSpace <---{TCP 3493}---> QNAP                    (NUT Server)              (NUT Client)

P.S. 现在（2025 年 12 月）极空间已经支持 NUT Slave 模式了，各种参数都可以自定义，所以更好的方式应该是上述的第一种。不过我懒得去改接线了，先这样吧。又不是不能用.jpg

在极空间上的操作

因为 QNAP 的弱智系统只能接受固定的用户名、密码和 UPS 名称，所以需要修改极空间的 NUT Server 配置。

首先要拿到极空间 NAS 的 ssh 和 root 权限，这里就不赘述了。登上去以后：

ls -al /etc/nut# lrwxrwxrwx 1 root root 33 Sep 17  2024 /etc/nut -> /zspace/applications/services/nutcd /zspace/applications/services/nutls -a ./# .       config                     restart.sh         setting.json  ups.conf     upssched# ..      external_ups_setting.json  restart_driver.sh  start.sh      upsd.conf    upssched-cmd.sh# client  nut.conf                   restart_upsd.sh    stop.sh       upsd.users   upssched.conf# conf    realstart.sh               server             u2600_tools   upsmon.conf

然后 cat ./server/nut-server.service 看看配置文件在哪（后续系统版本升级后实际路径可能会变，最好确认一下）：

#!/bin/sh#use upsd.confexport NUT_CONFPATH=/zspace/applications/services/nut/config/sbin/upsd -u root

看看配置文件 ./config/upsd.conf：

# Network UPS Tools: example upsd configuration file## ... 其他注释省略 ...# =======================================================================# LISTEN <address> [<port>]LISTEN 127.0.0.1 3493LISTEN ::1 3493

把这里的 127.0.0.1 改成 0.0.0.0，允许局域网（QNAP NAS）访问。或者也可以起一个 socat 做转发，都行。有需要的话也可以配一下 ACL，只允许 QNAP IP 访问。

cp /zspace/applications/services/nut/config/upsd.conf ~/upsd.conf.baksed -i 's/127.0.0.1/0.0.0.0/g' /zspace/applications/services/nut/config/upsd.conf

再看看用户配置文件 ./config/upsd.users：

# Network UPS Tools: Example upsd.users## ... 其他注释省略 ...# --------------------------------------------------------------------------[upsmaster]        password = sekret        upsmon master        actions = SET        instcmds = ALL[nut]        password = nut        upsmon slave        allowfrom = %

往里面加上 QNAP 需要的用户：

cp /zspace/applications/services/nut/config/upsd.users ~/upsd.users.bakcat >> /zspace/applications/services/nut/config/upsd.users << EOF[admin]        password = 123456        upsmon slave        allowfrom = %EOF

然后再看看 UPS 配置文件 ./config/ups.conf：

# Network UPS Tools: example ups.conf## ... 其他注释省略 ...# ------------------------maxretry = 3xretry = 5pollinterval = 15[ups0]        driver = usbhid-ups        port = auto        desc = "nut ups"        lowbatt = 15        pollfreq = 15        offdelay = 60

往里面加上 QNAP 需要的 UPS 名称：

cp /zspace/applications/services/nut/config/ups.conf ~/ups.conf.bakcat >> /zspace/applications/services/nut/config/ups.conf << EOF[qnapups]        driver = usbhid-ups        port = auto        desc = "zspace ups for qnap"        lowbatt = 15        pollfreq = 15        offdelay = 60EOF

最后，重启 NUT 服务：

本来想直接执行 /zspace/applications/services/nut/restart.sh 重启服务的，但似乎缺少某些环境变量，可能不是拿来直接调用的。

可以直接去极空间的网页面板，设置 > UPS 设置，把开关关闭然后再打开就行了。再检查下进程，看到 qnapups 就算成功了。

ps aux | grep ups# root     29716  /usr/share/nut/usbhid-ups -a ups0 -u root# root     29718  /usr/share/nut/usbhid-ups -a qnapups -u root# root     29722  /sbin/upsd -u root

在 QNAP 上的操作

不需要做什么，在网页面板上填入极空间 NAS 的局域网 IP 就能连上了。

通过 upsc qnapups@192.168.1.4 查看 UPS 信息：

battery.charge: 100battery.charge.low: 10battery.mfr.date: 2001/01/01battery.runtime: 3618battery.runtime.low: 120battery.type: PbAcbattery.voltage: 13.6battery.voltage.nominal: 12.0device.mfr: American Power Conversiondevice.model: Back-UPS BK650M2-CHdevice.type: upsdriver.name: usbhid-ups

顺便看看 QNAP 上的 NUT 服务配置：

ls -al /etc/config# lrwxrwxrwx 1 admin administrators 21 2025-12-31 13:14 /etc/config -> /mnt/HDA_ROOT/.configls -a /mnt/HDA_ROOT/.config/ups# .  ..  ups.conf  upsd.conf  upsd.users  upsmon.conf

配置文件在 /mnt/HDA_ROOT/.config/ups/upsmon.conf：

# Network UPS Tools: example upsmon configuration## ... 其他注释省略 ...# --------------------------------------------------------------------------MONITOR qnapups@192.168.1.4 1 admin 123456 slave#MONITOR zspaceups@192.168.1.4 1 upsmaster sekret slave# ... 其他注释省略 ...RUN_AS_USER adminMINSUPPLIES 1SHUTDOWNCMD "/sbin/shutdown -h +0"POLLFREQ 5POLLFREQALERT 5HOSTSYNC 15DEADTIME 15POWERDOWNFLAG /etc/killpowerRBWARNTIME 43200NOCOMMWARNTIME 300FINALDELAY 5

其实我之前也试过直接改这个文件，把 MONITOR 里写死的配置改成极空间的配置。但是试下来发现改完以后虽然服务是跑起来了，但是在 QNAP 的网页面板上不会显示 UPS 信息和已连接到 UPS 设备的图标。也不知道是这系统魔改了什么地方，担心会出现奇怪的问题，遂作罢。

如果你需要将 QNAP 作为 NUT Server，那可以关注 upsd.conf 和 upsd.users 文件，网上也有相关教程。

可视化 UPS 监控面板

因为 NUT 的网络协议走的是 TCP 3493，所以就算是异地的 UPS，组建虚拟局域网后也可以互相访问。

这里推荐一个开源的 NUT UPS 管理面板 PeaNUT，用起来挺方便的。

本文记录 https://docs.halo.run 集成 Shiki 代码高亮的过程。

引言

从 Halo 1.x 开始，我们就一直在使用 Docusaurus 来构建 Halo 的文档。直到 Halo 2.21，我们已经累积了大量的文档，期间发现代码块高亮的问题难以解决。Docusaurus 默认使用 Prism.js 来渲染代码块，且几乎没有其他选择。而我们的文档中使用的一些语言或框架（如 Vue），Prism 并没有提供高亮支持，因此长期以来这些代码块都没有显示语法高亮。即使是 Prism 所支持的语言，渲染出来的语法高亮效果也不尽如人意。

直到后来了解到了 https://shiki.style/，一个较新的代码高亮库，基于与 VSCode 同源的 TextMate 代码高亮引擎，渲染出来的代码效果与 VSCode 一致，并且支持现在主流语言和框架代码的高亮。我认为这几乎是当前各方面最优的代码高亮库。后面我们也为 Halo 开发了 Shiki 代码高亮插件，表现十分良好。因此最近也考虑将 Halo 文档中的代码高亮渲染改为使用 Shiki。好在搜索一番后，已经有了一个广泛讨论的 issue：https://github.com/facebook/docusaurus/issues/9122，并且里面也有人提供了可行的方案。于是我按照这个方案并添加了一些额外功能，本文将记录实现的完整过程。如果你也在用 Docusaurus，并且对 Shiki 有需求，可以参考本文。

背景

• 目前使用的 Docusaurus 版本是 3.8.0

安装依赖

Docusaurus 的 Markdown 引擎核心为 https://mdxjs.com/，而 MDX 内部基于 remark 和 rehype，因此 Docusaurus 实际上预留了可以添加 rehype 插件的配置，所以可以直接使用 Shiki 官方的 rehype 插件。

pnpm add @shikijs/rehype shiki -D

添加配置

const { bundledLanguages } = require("shiki");
const { default: rehypeShiki } = require("@shikijs/rehype");

/** @type {import('@docusaurus/types').Config} */
const config = {
  // ...
  presets: [
    [
      "classic",
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          // ...
// [!code ++:11]
          beforeDefaultRehypePlugins: [
            [
              rehypeShiki,
              {
                theme: "catppuccin-mocha",
                langs: Object.keys(bundledLanguages),
                // or
                // langs: ['js', 'ts']
              },
            ],
          ],
          // ...
        },
      }),
    ],
  ],
  // ...
};

其中，langs 可以只填写所需的语言列表，我这里为了省事直接添加 Shiki 所有语言，主要是因为文档太多，已经懒得去统计用到了哪些语言。

此外，theme 也可以指定多主题，如果需要让文档的暗色和亮色模式下代码块的主题不同，可以按照下面的方式更改：

const { bundledLanguages } = require("shiki");
const { default: rehypeShiki } = require("@shikijs/rehype");

/** @type {import('@docusaurus/types').Config} */
const config = {
  // ...
  presets: [
    [
      "classic",
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          // ...
          beforeDefaultRehypePlugins: [
            [
              rehypeShiki,
              {
// [!code --]
                theme: "catppuccin-mocha",
// [!code ++:4]
                themes: {
                  light: "github-light",
                  dark: "github-dark"
                },
                langs: Object.keys(bundledLanguages),
                // or
                // langs: ['js', 'ts']
              },
            ],
          ],
          // ...
        },
      }),
    ],
  ],
  // ...
};

module.exports = config;

然后在 custom.css 中添加：

[data-theme="dark"] pre {
  color: var(--shiki-dark) !important;
  background-color: var(--shiki-dark-bg) !important;
}
[data-theme="dark"] pre span {
  color: var(--shiki-dark) !important;
}

由于我期望亮色和暗色模式下都使用暗色的代码块主题，所以没有添加多主题配置。

组件覆盖

由于需要完全让 @shikijs/rehype 接管 Markdown 文档中的代码块渲染，我们需要覆盖 Docusaurus 内部 Pre/Code 的组件，避免被默认的 Prism 处理。Docusaurus 默认提供了 CLI 用于导出 Docusaurus 主题中的组件。

npx docusaurus swizzle @docusaurus/theme-classic MDXComponents/Code --typescript --eject

然后打开 src/theme/MDXComponents/Code.tsx 并修改为：

import type { ComponentProps, ReactNode } from "react";
import React from "react";
import CodeInline from "@theme/CodeInline";
import type { Props } from "@theme/MDXComponents/Code";

function shouldBeInline(props: Props) {
  return (
    // empty code blocks have no props.children,
    // see https://github.com/facebook/docusaurus/pull/9704
    typeof props.children !== "undefined" &&
    React.Children.toArray(props.children).every(
      (el) => typeof el === "string" && !el.includes("\n")
    )
  );
}

// [!code ++:3]
function CodeBlock(props: ComponentProps<"code">): JSX.Element {
  return <code {...props} />;
}

export default function MDXCode(props: Props): ReactNode {
  return shouldBeInline(props) ? (
    <CodeInline {...props} />
  ) : (
    <CodeBlock {...(props as ComponentProps<typeof CodeBlock>)} />
  );
}

npx docusaurus swizzle @docusaurus/theme-classic MDXComponents/Pre --typescript --eject

然后打开 src/theme/MDXComponents/Pre.tsx 并修改为：

import React, { type ReactNode } from "react";
import type { Props } from "@theme/MDXComponents/Pre";
export default function MDXPre(props: Props): ReactNode | undefined {
  return <pre {...props} />;
}

小插曲：当时到了这一步的时候，突然意识到似乎可以复用之前为 Halo 开发 Shiki 插件时发布的 NPM 包（@halo-dev/shiki-code-element）。因为这个包封装了一个 Web Component，所以肯定可以用在这里，只需要在 pre 标签外包裹一个 shiki-code 即可。尝试了一下确实可行，但这样就必须在客户端渲染了。虽然可行，但始终不如在构建阶段就渲染好。虽然可以尝试使用 Lit SSR，但考虑到文档中有一些代码块使用了 Title Meta，而目前 @halo-dev/shiki-code-element 还不支持，所以放弃了这个方案。

完成这一步之后，就可以尝试启动开发服务器了。不出意外的话，代码块就可以正常使用 Shiki 来渲染了。

添加标题支持

原来 Docusaurus 的默认方案是支持为代码块添加顶部标题的，切换到 Shiki 之后，这一部分需要自行实现，以下是具体步骤：

首先为 Shiki 添加一个自定义的 Transformer，用于解析标题的书写语法和添加代码块参数：

创建 src/shiki/meta-transformer.js：

function parseTitleFromMeta(meta) {
  if (!meta) {
    return "";
  }
  const kvList = meta.split(" ").filter(Boolean);
  for (const item of kvList) {
    const [k, v = ""] = item.split("=").filter(Boolean);
    if (k === "title" && v.length > 0) {
      return v.replace(/["'`]/g, "");
    }
  }
  return "";
}

export function transformerAddMeta() {
  return {
    name: "shiki-transformer:add-meta",
    pre(pre) {
      const title = parseTitleFromMeta(this.options.meta?.__raw);
      if (title.length > 0) {
        pre.properties = {
          ...pre.properties,
          "data-title": title,
        };
      }
      return pre;
    },
  };
}

然后修改配置：

const { bundledLanguages } = require("shiki");
const { default: rehypeShiki } = require("@shikijs/rehype");
const { transformerAddMeta } = require("./src/shiki/meta-transformer");

/** @type {import('@docusaurus/types').Config} */
const config = {
  // ...
  presets: [
    [
      "classic",
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          // ...
          beforeDefaultRehypePlugins: [
            [
              rehypeShiki,
              {
                theme: "catppuccin-mocha",
                langs: Object.keys(bundledLanguages),
// [!code ++:3]
                transformers: [
                  transformerAddMeta(),
                ]
              },
            ],
          ],
          // ...
        },
      }),
    ],
  ],
  // ...
};

修改 Pre.tsx 显示标题：

import React, { type ReactNode } from "react";
import type { Props } from "@theme/MDXComponents/Pre";

type PreWithDataTitle = Props & { "data-title"?: string };

export default function MDXPre(props: Props): ReactNode | undefined {
  const title = props["data-title"];
  return (
    <div
      style={{
        ...props.style,
        borderRadius: "var(--ifm-pre-border-radius)",
      }}
      className="shiki-code-wrapper"
    >
      {title && (
        <div className="shiki-code-header">
          <span>{title}</span>
        </div>
      )}
      <div className="shiki-code-content">
        <pre {...props} ref={preRef} />
      </div>
    </div>
  );
}

这里还修改了 MDXPre 标签的组件结构，为后续的功能做准备，其中最外层的 div 添加的 style 属性来自于 Shiki 渲染结果的 pre 标签的样式，包含背景色和字体默认颜色。

最后我们需要为自定义的 MDXPre 组件结构添加样式，这里为了让结构看起来更清晰，我引入了 SASS 插件：

# 安装所需依赖
pnpm add docusaurus-plugin-sass sass -D

修改配置文件：

/** @type {import('@docusaurus/types').Config} */
const config = {
  // ...
  presets: [
    [
      "classic",
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        // ...
        theme: {
// [!code --]
          customCss: require.resolve("./src/css/custom.css"),
// [!code ++:4]
          customCss: [
            require.resolve("./src/css/custom.css"),
            require.resolve("./src/css/shiki.scss"),
          ],
        },
      }),
    ],
  ],
// [!code ++]
  plugins: [require.resolve("docusaurus-plugin-sass")],
};

然后创建 src/css/shiki.scss：

.shiki-code-wrapper {
  overflow: hidden;
  margin-bottom: var(--ifm-leading);
  color-scheme: dark;

  .shiki-code-header {
    padding: 0.5rem 0.75rem;
    border-bottom: 1px solid var(--ifm-color-gray-700);
    font-size: var(--ifm-code-font-size);
  }
}

这样就支持使用原有的语法为代码块添加标题了。

显示行号

Shiki 原生并不支持在渲染的 HTML 结果中包含行号信息，但社区中有人提供了一种使用纯 CSS 实现的方案，详见：https://github.com/shikijs/shiki/issues/3#issuecomment-830564854

修改 shiki.scss：

.shiki-code-wrapper {
  overflow: hidden;
  margin-bottom: var(--ifm-leading);
  color-scheme: dark;

  .shiki-code-header {
    padding: 0.5rem 0.75rem;
    border-bottom: 1px solid var(--ifm-color-gray-700);
    font-size: var(--ifm-code-font-size);
  }
// [!code ++:36]
  .shiki-code-content {
    position: relative;

    pre {
      position: relative;
      padding: 0.75rem;
      margin: 0;
      border-radius: initial;
      code {

        counter-reset: step;
        counter-increment: step 0;

        .line {
          position: relative;
        }

        // line numbers start
        .line::before {
          content: counter(step);
          counter-increment: step;
          width: 0.6rem;
          margin-right: 1.1rem;
          display: inline-block;
          text-align: right;
          color: rgba(115, 138, 148, 0.5);
          user-select: none;
        }

        .line:last-child:empty::before {
          content: none;
          counter-increment: none;
        }
        // line numbers end
      }
    }
  }
}

这样就可以默认为所有代码块添加行号显示了。

复制按钮

Docusaurus 默认的代码块有复制按钮，改为 Shiki 之后这部分也需要自行实现，以下是具体步骤：

修改 src/theme/MDXComponents/Pre.tsx：

import React, { type ReactNode, useRef, useState } from "react";
import type { Props } from "@theme/MDXComponents/Pre";

type PreWithDataTitle = Props & { "data-title"?: string };

export default function MDXPre(props: PreWithDataTitle): ReactNode | undefined {
  const title = props["data-title"];
// [!code ++:11]
  const preRef = useRef<HTMLPreElement>(null);
  const [copied, setCopied] = useState(false);

  const handleCopy = () => {
    const code = preRef.current?.innerText || preRef.current?.textContent || "";

    copyText(code, () => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    });
  };

  return (
    <div
      style={{
        ...props.style,
        borderRadius: "var(--ifm-pre-border-radius)",
      }}
      className="shiki-code-wrapper"
    >
      {title && (
        <div className="shiki-code-header">
          <span>{title}</span>
        </div>
      )}
      <div className="shiki-code-content">
// [!code ++:8]
        <button
          className="shiki-code-copy-button"
          onClick={handleCopy}
          title={copied ? "已复制!" : "复制代码"}
          style={{ ...props.style }}
        >
          <i className={copied ? "tabler--check" : "tabler--copy"}></i>
        </button>
        <pre {...props} ref={preRef} />
      </div>
    </div>
  );
}

// [!code ++:24]
export function copyText(text: string, cb: () => void) {
  if (navigator.clipboard) {
    navigator.clipboard.writeText(text).then(() => {
      cb();
    });
  } else {
    const textArea = document.createElement("textarea");
    textArea.value = text;
    textArea.style.position = "fixed";
    textArea.style.opacity = "0";
    document.body.appendChild(textArea);
    textArea.focus();
    textArea.select();
    try {
      const successful = document.execCommand("copy");
      if (successful) {
        cb();
      }
    } catch (err) {
      console.error("Fallback: Oops, unable to copy", err);
    }
    document.body.removeChild(textArea);
  }
}

添加样式：

.shiki-code-wrapper {
  overflow: hidden;
  margin-bottom: var(--ifm-leading);
  color-scheme: dark;

  .shiki-code-header {
    padding: 0.5rem 0.75rem;
    border-bottom: 1px solid var(--ifm-color-gray-700);
    font-size: var(--ifm-code-font-size);
  }

  .shiki-code-content {
    position: relative;

    pre {
      position: relative;
      padding: 0.75rem;
      margin: 0;
      border-radius: initial;
      code {

        counter-reset: step;
        counter-increment: step 0;

        .line {
          position: relative;
        }

        // line numbers start
        .line::before {
          content: counter(step);
          counter-increment: step;
          width: 0.6rem;
          margin-right: 1.1rem;
          display: inline-block;
          text-align: right;
          color: rgba(115, 138, 148, 0.5);
          user-select: none;
        }

        .line:last-child:empty::before {
          content: none;
          counter-increment: none;
        }
        // line numbers end
      }
    }
// [!code ++:15]
    .shiki-code-copy-button {
      position: absolute;
      top: 0.5rem;
      right: 0.5rem;
      opacity: 0;
      z-index: 2;
      width: 2rem;
      height: 2rem;
      display: flex;
      align-items: center;
      justify-content: center;
      padding: 0.4rem;
      border: none;
      cursor: pointer;
    }
  }
// [!code ++:33]
  &:hover {
    .shiki-code-copy-button {
      opacity: 1;
    }
  }

  .tabler--copy {
    display: inline-block;
    width: 28px;
    height: 28px;
    --svg: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cg fill='none' stroke='%23000' stroke-linecap='round' stroke-linejoin='round' stroke-width='2'%3E%3Cpath d='M7 9.667A2.667 2.667 0 0 1 9.667 7h8.666A2.667 2.667 0 0 1 21 9.667v8.666A2.667 2.667 0 0 1 18.333 21H9.667A2.667 2.667 0 0 1 7 18.333z'/%3E%3Cpath d='M4.012 16.737A2 2 0 0 1 3 15V5c0-1.1.9-2 2-2h10c.75 0 1.158.385 1.5 1'/%3E%3C/g%3E%3C/svg%3E");
    background-color: currentColor;
    -webkit-mask-image: var(--svg);
    mask-image: var(--svg);
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-size: 100% 100%;
    mask-size: 100% 100%;
  }

  .tabler--check {
    display: inline-block;
    width: 28px;
    height: 28px;
    --svg: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='none' stroke='%23000' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='m5 12l5 5L20 7'/%3E%3C/svg%3E");
    background-color: currentColor;
    -webkit-mask-image: var(--svg);
    mask-image: var(--svg);
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-size: 100% 100%;
    mask-size: 100% 100%;
  }
}

这样就可以在鼠标悬停到代码块时显示复制按钮了。

集成必要的 Transformer

Shiki 官方提供了一些非常有用的 Transformers，比如行高亮、代码对比等，这里根据自身需要添加即可。

pnpm add -D @shikijs/transformers

const { bundledLanguages } = require("shiki");
const { default: rehypeShiki } = require("@shikijs/rehype");
const { transformerAddMeta } = require("./src/shiki/meta-transformer");
// [!code ++:4]
const { transformerMetaHighlight } = require("@shikijs/transformers");
const { transformerNotationDiff } = require("@shikijs/transformers");
const { transformerNotationFocus } = require("@shikijs/transformers");
const { transformerNotationErrorLevel } = require("@shikijs/transformers");

/** @type {import('@docusaurus/types').Config} */
const config = {
  // ...
  presets: [
    [
      "classic",
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          // ...
          beforeDefaultRehypePlugins: [
            [
              rehypeShiki,
              {
                theme: "catppuccin-mocha",
                langs: Object.keys(bundledLanguages),
                transformers: [
// [!code ++:8]
                  // 行高亮，使用 Meta 信息的方式，比如 ```java {1}
                  transformerMetaHighlight(),
                  // 代码对比，使用注释的方式
                  transformerNotationDiff(),
                  // 行聚焦，使用注释的方式
                  transformerNotationFocus(),
                  // 行高亮的错误和警告变体，使用注释的方式
                  transformerNotationErrorLevel(),
                  transformerAddMeta(),
                ]
              },
            ],
          ],
          // ...
        },
      }),
    ],
  ],
  // ...
};

这些 Transformers 只是为对应的行添加了 class，我们需要自行实现样式。以下是完整的 shiki.scss：

.shiki-code-wrapper {
  overflow: hidden;
  margin-bottom: var(--ifm-leading);
  color-scheme: dark;

  .shiki-code-header {
    padding: 0.5rem 0.75rem;
    border-bottom: 1px solid var(--ifm-color-gray-700);
    font-size: var(--ifm-code-font-size);
  }

  .shiki-code-content {
    position: relative;

    pre {
      position: relative;
      padding: 0.75rem;
      margin: 0;
      border-radius: initial;
      code {
        z-index: 1;
        display: block;
        width: max-content;
        position: relative;
        min-width: 100%;

        counter-reset: step;
        counter-increment: step 0;

        .line {
          position: relative;
        }

        // line numbers start
        .line::before {
          content: counter(step);
          counter-increment: step;
          width: 0.6rem;
          margin-right: 1.1rem;
          display: inline-block;
          text-align: right;
          color: rgba(115, 138, 148, 0.5);
          user-select: none;
        }

        .line:last-child:empty::before {
          content: none;
          counter-increment: none;
        }
        // line numbers end

        // highlighted lines start
        .highlighted {
          width: 100%;
          display: inline-block;
          position: relative;
        }

        .highlighted::after {
          content: "";
          position: absolute;
          top: 0;
          bottom: 0;
          left: -0.75rem;
          right: -0.75rem;
          background: rgba(101, 117, 133, 0.16);
          border-left: 1px solid rgba(34, 197, 94, 0.8);
          z-index: 0;
        }

        .highlighted.error::after {
          background: rgba(244, 63, 94, 0.16) !important;
        }

        .highlighted.warning::after {
          background: rgba(234, 179, 8, 0.16) !important;
        }
        // highlighted lines end
      }

      // focus line start
      &.has-focused .line:not(.focused) {
        opacity: 0.7;
        filter: blur(0.095rem);
        transition: filter 0.35s, opacity 0.35s;
      }

      &.has-focused:hover .line:not(.focused) {
        opacity: 1;
        filter: blur(0);
      }
      // focus line end

      // diff start
      &.has-diff .diff {
        width: 100%;
        display: inline-block;
        position: relative;
      }

      &.has-diff .diff.remove::before {
        content: "-";
      }

      &.has-diff .diff.add::before {
        content: "+";
      }

      &.has-diff .diff.remove::after {
        content: "";
        position: absolute;
        top: 0;
        bottom: 0;
        left: -0.75rem;
        right: -0.75rem;
        background: rgb(239 68 68 / 0.15);
        border-left: 1px solid rgb(239 68 68 / 0.8);
        z-index: -1;
      }

      &.has-diff .diff.add::after {
        content: "";
        position: absolute;
        top: 0;
        bottom: 0;
        left: -0.75rem;
        right: -0.75rem;
        background: rgb(34 197 94 / 0.15);
        border-left: 1px solid rgb(34 197 94 / 0.8);
        z-index: -1;
      }
      // diff end
    }

    .shiki-code-copy-button {
      position: absolute;
      top: 0.5rem;
      right: 0.5rem;
      opacity: 0;
      z-index: 2;
      width: 2rem;
      height: 2rem;
      display: flex;
      align-items: center;
      justify-content: center;
      padding: 0.4rem;
      border: none;
      cursor: pointer;
    }
  }

  &:hover {
    .shiki-code-copy-button {
      opacity: 1;
    }
  }

  .tabler--copy {
    display: inline-block;
    width: 28px;
    height: 28px;
    --svg: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cg fill='none' stroke='%23000' stroke-linecap='round' stroke-linejoin='round' stroke-width='2'%3E%3Cpath d='M7 9.667A2.667 2.667 0 0 1 9.667 7h8.666A2.667 2.667 0 0 1 21 9.667v8.666A2.667 2.667 0 0 1 18.333 21H9.667A2.667 2.667 0 0 1 7 18.333z'/%3E%3Cpath d='M4.012 16.737A2 2 0 0 1 3 15V5c0-1.1.9-2 2-2h10c.75 0 1.158.385 1.5 1'/%3E%3C/g%3E%3C/svg%3E");
    background-color: currentColor;
    -webkit-mask-image: var(--svg);
    mask-image: var(--svg);
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-size: 100% 100%;
    mask-size: 100% 100%;
  }

  .tabler--check {
    display: inline-block;
    width: 28px;
    height: 28px;
    --svg: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='none' stroke='%23000' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='m5 12l5 5L20 7'/%3E%3C/svg%3E");
    background-color: currentColor;
    -webkit-mask-image: var(--svg);
    mask-image: var(--svg);
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-size: 100% 100%;
    mask-size: 100% 100%;
  }
}

至此，一个比较好看、功能丰富的代码高亮改造方案就完成了，具体修改代码也可以查阅 Halo 文档的 PR：https://github.com/halo-dev/docs/pull/521，也可以访问 Halo 文档查看修改之后的效果。

参考资料

• https://github.com/facebook/docusaurus/issues/9122

• https://lachieh.github.io/docusaurus-with-shiki-rehype/docs/intro/

• https://github.com/shikijs/shiki/issues/3

• https://docusaurus.io/docs/markdown-features/plugins

原文地址：https://www.lxware.cn/archives/halo-meilisearch

Halo 从 2.0 版本开始支持了全文搜索功能，自带的 Lucene 搜索引擎在轻度使用场景下可以满足需求，但在重度依赖搜索功能的场景下，可能在搜索速度和用户体验上存在不足，这时我们会更推荐使用独立的搜索引擎。

本文将介绍如何使用 https://www.meilisearch.com/ 搜索引擎来提升 Halo 网站的搜索体验。

搭建 Meilisearch 服务

部署 Meilisearch 服务通常有两种方式：你可以选择自行在服务器上托管，或者使用 Meilisearch 官方提供的云服务。

云服务

访问 https://www.meilisearch.com/cloud 注册账号，根据引导创建项目。创建完成后，可以在控制台获取实例地址和 Master Key。

需要特别注意 Meilisearch 云服务的计费方式。

自托管

下面介绍两种常见的部署方式：

使用 Docker Compose 独立编排部署

这种方式适合多个项目需要同时使用一个 Meilisearch 服务的场景。 部署完成后，你可以配置域名和反向代理来暴露服务到公网。

services:
  meilisearch:
  image: getmeili/meilisearch:v1.15
  restart: unless-stopped
  ports:
    - "7700:7700"
  environment:
    - MEILI_ENV=production
// [!code highlight]
    - MEILI_MASTER_KEY=<your-super-secret-master-key-here>
  volumes:
    - meilisearch_data:/meili_data

volumes:
  meilisearch_data:
    driver: local

与 Halo 的 Compose 编排一起部署

结合 使用 Docker Compose 部署 Halo 的示例，将 Meilisearch 服务添加到 docker-compose.yml 文件中。

通过这种方式部署之后，插件设置中的 Meilisearch 服务地址 应该是 http://meilisearch:7700（即服务在同一 Compose 网络下可通过服务名访问）

meilisearch:
  image: getmeili/meilisearch:v1.15
  restart: on-failure:3
  networks:
    - halo_network
  volumes:
    - ./meilisearch-data:/meili_data
  environment:
    - MEILI_ENV=production
// [!code highlight]
    - MEILI_MASTER_KEY=<your-super-secret-master-key-here>

version: "3"

services:
  halo:
    image: registry.fit2cloud.com/halo/halo:2.21
    restart: on-failure:3
    depends_on:
    halodb:
      condition: service_healthy
    networks:
    halo_network:
    volumes:
      - ./halo2:/root/.halo2
    ports:
      - "8090:8090"
    healthcheck:
    test:
      ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"]
    interval: 30s
    timeout: 5s
    retries: 5
    start_period: 30s
    environment:
      - JVM_OPTS=-Xmx256m -Xms256m
    command:
      - --spring.r2dbc.url=r2dbc:pool:postgresql://halodb/halo
      - --spring.r2dbc.username=halo
      - --spring.r2dbc.password=openpostgresql
      - --spring.sql.init.platform=postgresql
      - --halo.external-url=http://localhost:8090/
  halodb:
    image: postgres:15.4
    restart: on-failure:3
    networks:
    halo_network:
    volumes:
      - ./db:/var/lib/postgresql/data
    healthcheck:
    test: ["CMD", "pg_isready"]
    interval: 10s
    timeout: 5s
    retries: 5
    environment:
      - POSTGRES_PASSWORD=openpostgresql
      - POSTGRES_USER=halo
      - POSTGRES_DB=halo
      - PGUSER=halo
// [!code focus:10]
  meilisearch:
    image: getmeili/meilisearch:v1.15
    restart: on-failure:3
    networks:
      - halo_network
    volumes:
      - ./meilisearch-data:/meili_data
    environment:
      - MEILI_ENV=production
      - MEILI_MASTER_KEY=<your-super-secret-master-key-here>

networks:
  halo_network:

详细的部署方式可以参考 Meilisearch 官方文档：https://www.meilisearch.com/docs/learn/self_hosted/install_meilisearch_locally

安装插件

之前 Halo 社区中已经有人开发了 Meilisearch 插件，但已经不再维护，因此这里我们选择使用 Halo 官方提供的插件。

1. 下载插件，目前提供以下两种下载方式：

   • Halo 应用市场：https://www.halo.run/store/apps/app-7mb5szjt

   • GitHub Releases：访问 Releases 下载 Assets 中的 JAR 文件。

2. 安装插件，插件安装和更新方式可参考：https://docs.halo.run/user-guide/plugins

配置插件

1. 进入插件设置，配置 Meilisearch 服务地址 和 Master Key。索引名称 可以选择使用默认的 halo 或者自定义（如果你的 Meilisearch 服务会被多个项目使用，建议自定义索引名称）。

   

2. 进入插件扩展配置，在 扩展点定义 中选择 搜索引擎，然后选择使用 Meilisearch。

   

数据概览

配置完插件后，我们可以进入插件的 数据概览 页面，查看 Meilisearch 的索引数据。

在这个页面中，你还可以重建索引或测试搜索功能。

对比

Lucene（默认搜索引擎）与 Meilisearch 的实际对比：

Meilisearch	Lucene（默认）

通过实际使用可以发现，Meilisearch 的搜索结果更加准确，搜索速度更快，并且支持更灵活的搜索语法，无需用户掌握复杂的搜索表达式即可获得理想的搜索结果。

注意

1. 如果配置完 Meilisearch 插件之后无法搜索，可以尝试重建一次索引。

2. 安装 Meilisearch 插件之后仍然需要https://www.halo.run/store/apps/app-DlacW插件，Meilisearch 插件仅仅是提供服务，不会提供 UI。

原文地址：https://www.lxware.cn/archives/halo-content-tools

在 Halo 社区中，导入 Markdown 和 Word 文档的需求一直很高，但社区一直缺乏完善的解决方案。其主要原因在于 Markdown 和 Word 的文档格式较为复杂，难以完美支持所有格式特性，且图片资源的处理存在技术难点。

现在，社区中已经有了一个插件可以很好地支持导入 Markdown 和 Word 文档，它就是 https://www.halo.run/store/apps/app-SUvBR。该插件不仅支持导入 Markdown 和 Word 文档，还能够智能处理和导入图片资源，为用户提供了完整的文档迁移解决方案。

安装

可以通过以下两种方式安装插件：

1. 访问 https://www.halo.run/store/apps/app-SUvBR 页面直接下载

2. 在 Console 内置的应用市场中搜索 内容助手 进行安装

导入 Markdown 文档

安装并启用插件后，就可以在 Console 侧边菜单的工具中找到 文章导入 的入口。点击进入后，选择 Markdown 导入 选项卡即可开始导入，如下图：

功能详解

1. 选择 Markdown 文件：用于选择单个 Markdown 文档，支持 .md 格式文件。

2. 选择 Markdown 文件夹：用于选择包含 Markdown 文档的文件夹。选择文件夹后，系统会自动扫描其中的所有 Markdown 文档以及图片资源（如有）。

3. 选择图片文件夹：用于选择 Markdown 文档中引用的图片资源。选择文件夹后，系统会自动扫描其中的所有图片资源并在导入时自动关联。

4. 转为富文本格式：默认情况下，导入的 Markdown 文档会保持原有的 Markdown 格式。如果勾选此选项，系统会将文档转换为富文本格式，便于后续使用 Halo 的默认编辑器进行编辑。

使用场景

• 从其他博客平台或写作工具迁移文章内容

• 导入使用本地 Markdown 编辑器创作的文章

• 批量导入历史文档和资料

注意事项

1. 导入 Markdown 文档后，如果需要在 Console 中编辑文章，请确保已经安装了任意一个 Markdown 编辑器插件，否则无法正常打开编辑页面。

2. 如果 Markdown 文档中引用了本地图片资源，请在导入前选择存放图片的文件夹，否则图片将无法正确上传和关联。

3. 系统支持自动解析 Front Matter（文档头部的元数据），包括标题、别名（slug）、描述、摘要、分类、标签等信息。

操作示例

选择 Markdown 文件：

选择图片文件夹（如果文档包含本地图片）：

点击导入，等待导入完成：

检查文章与图片资源是否导入成功：

导入 Word 文档

进入 文章导入 页面后，选择 Word（.docx）导入 选项卡，如下图：

功能详解

1. 选择 Word 文档：用于选择单个 Word 文档，支持 .doc 和 .docx 格式。

2. 选择 Word 文档文件夹：用于批量选择包含 Word 文档的文件夹。

3. 转为 Markdown 格式：默认情况下，导入的 Word 文档会转换为富文本格式。如果希望后续使用 Markdown 编辑器编辑文章，请勾选此选项将内容转换为 Markdown 格式。

使用场景

• 将公司内部的 Word 文档转换为博客文章

• 配合 https://maxkb.cn/ 智能知识库，建立企业知识管理体系

• 从传统文档工具迁移内容到现代化的管理平台

注意事项

1. 由于 Word 文档格式的复杂性，系统可能无法完美解析所有内容格式，建议导入后进行适当调整。

2. 系统支持自动导入 Word 文档中的图片资源，但其他类型的嵌入对象暂不支持。

3. 图片会上传到与个人中心关联的存储策略，请提前在用户设置中配置相关参数。

操作示例

选择 Word 文档：

点击导入，等待导入完成：

检查文章是否导入成功：

丰富的内容管理功能

除了核心的导入功能，内容助手还提供了丰富的内容管理功能：

格式转换

支持 Markdown 与富文本格式的双向转换，让用户可以根据编辑需求灵活切换文档格式。你可以在文章管理页面点击文章的 ··· 按钮，在转换菜单中选择相应的格式转换选项，也可以在文章编辑页面顶部的编辑器选择框中选择 内容格式转换器 进行转换。

文章导出

支持将文章导出为多种格式，方便内容备份和分享：

• 以原格式导出：保持文章的原始格式进行导出

• 转换为 Markdown 并导出：将文章转换为 Markdown 格式后导出

• 转换为 PDF 并导出：将文章转换为 PDF 格式进行导出

文章克隆

提供文章克隆功能，便于基于现有文章创建相似内容。克隆后的文章会自动在标题后添加"（副本）"标识，并生成新的别名以避免冲突。

以上功能都可以在文章管理页面点击文章的 ··· 按钮找到相应选项。

总结

内容助手插件为 Halo 用户提供了完整的文档导入和内容管理解决方案，有效解决了 Markdown 和 Word 文档的导入难题。插件不仅支持智能处理图片资源，还提供了格式转换、文章导出、文章克隆、内容复制等丰富功能，能够满足大部分用户的内容管理需求。

无论你是从其他平台迁移内容，还是需要批量导入历史文档，内容助手都能为你提供便捷、高效的解决方案。如果你有文档导入或内容格式转换的需求，欢迎尝试使用内容助手插件。