群晖 DSM 7 部署（x86_64 / ARM）
fn-knock 提供面向 Synology DSM 7 的原生 SPK 套件，支持 x86_64、armv8 和 armv7 三个群晖套件架构。每个 SPK 只包含一种架构的原生二进制，必须选择与 NAS 匹配的文件；也不能把面向飞牛系统的 FPK 当作 DSM 安装包使用。
IMPORTANT
当前套件已经加固 DSM 冷启动时管理服务与 Go 网关的就绪同步。现有安装无法稳定启动时，不要先卸载或清空数据目录；从当前发布渠道下载相同套件架构的最新 SPK，在套件中心手动覆盖安装。正常覆盖升级会保留 /var/packages/fn-knock-synology/var。
套件以 DSM 创建的 fn-knock-synology 套件账户运行，不要求以 root 身份常驻运行。这样可以保留 DSM 的套件权限边界，但也意味着一部分需要直接管理宿主机的功能不可用。
安装前确认
- DSM 为
7.0-40000或更高版本，套件架构属于x86_64、armv8或armv7。 - 当前 DSM 账户属于 administrators 组；只有 DSM 管理员能打开 fn-knock 的管理界面。
- 网关默认使用
7999/tcp，不要与已有的反向代理、容器或另一套 fn-knock 冲突。 - 若计划从外网访问，提前确认域名、路由器/NAT、DSM 防火墙和 IPv6 / 运营商策略；安装成功不等于外网入口已经可用。
选择正确的 SPK
| 群晖套件架构 | 常见处理器类型 | 文件名 | 下载 |
|---|---|---|---|
x86_64 | Intel / AMD 64 位 | fn-knock-synology-x86_64-<版本>-<构建号>.spk | 下载 x86_64 SPK |
armv8 | ARM 64 位 | fn-knock-synology-armv8-<版本>-<构建号>.spk | 下载 ARMv8 SPK |
armv7 | ARM 32 位 | fn-knock-synology-armv7-<版本>-<构建号>.spk | 下载 ARMv7 SPK |
请根据群晖机型对应的 Package Arch（套件架构） 选择，不要仅凭产品名称或 CPU 品牌猜测。架构不匹配时，DSM 会拒绝安装；请重新下载正确的 SPK，不要修改文件名或尝试混用包内二进制。
安装 SPK
- 从上表或群晖下载页下载与 NAS 套件架构匹配的 SPK。
- 在 DSM 中打开“套件中心”，选择“手动安装”，上传该 SPK 并完成安装。
- 确认套件已启动，再从 DSM 主菜单打开“敲门 knock”。
- 在管理界面中完成认证、网关映射和证书配置。
管理界面通过已经登录的 DSM 桌面会话进入。DSM 主菜单会先打开会话启动页：
/webman/3rdparty/fn-knock-synology/launch.html启动页从 DSM 桌面窗口读取当前会话并完成校验，再进入 CGI 代理：
/webman/3rdparty/fn-knock-synology/index.cgi/不要收藏或直接打开这两个内部地址；离开 DSM 桌面上下文时，启动页无法读取会话。也不要把 7998 当成浏览器管理端口，或使用 DSM 根路径下的 /3rdparty/... 代替上述路径。
管理入口与端口
| 入口或端口 | 监听范围 | 用途 |
|---|---|---|
| DSM 主菜单中的“敲门 knock” | 启动页校验 DSM 已登录会话后进入 CGI 代理 | 唯一受支持的管理入口；仅 DSM 管理员可访问 |
7998 | 127.0.0.1 | 管理后端，由 DSM CGI 代理到本机 |
7997 | 本机内部 | 认证服务 |
7996 | 本机内部 | 网关内部通信 |
7999 | 网关公开监听 | 承接业务域名和网关流量 |
7991 | 不开放 | DSM 原生套件不使用此管理端口 |
不要向公网或局域网端口转发 7998、7997、7996，也不要为它们增加 DSM 防火墙放行规则。业务服务应只通过网关端口 7999 进入。
让网关安全地对外提供服务
SPK 会将 7999/tcp 声明为套件的公开网关端口，DSM 可以在防火墙界面识别这项端口资源；套件本身不会以 root 权限改写 DSM 的宿主机防火墙策略。是否允许外部连接，仍取决于以下各层配置：
- DSM 防火墙是否只向需要的来源、接口和端口放行
7999。 - 路由器是否将公网端口正确转发到 NAS，或是否已通过 FRP、Cloudflared 等隧道回源。
- IPv6 防火墙、上游运营商和域名解析是否与所选访问方式一致。
- 网关中的 Host 映射是否已配置证书、认证和目标服务地址。
管理入口仍应留在 DSM 桌面内，不要为方便管理而公开 7998。配置完成后，用移动网络等真实外部链路访问业务域名，检查请求是否经过网关并触发预期的登录策略。
DSM 版能力边界
| 能力 | DSM 原生 SPK 中的状态 |
|---|---|
| Host / 路径映射、认证、证书与 ACME | 支持 |
| 内置 FRP、Cloudflared | 支持，可作为网关的外部入口方案 |
| 直连授权、宿主机防火墙管理、智能连接 | 不支持 |
| fnOS 证书库同步、系统时钟同步 | 不支持 |
| Web 终端 | 支持连接管理员配置并确认主机指纹的远程 SSH 目标；不会打开 DSM 本机 Shell |
| SSH 安全 | 不支持 |
| 应用内自更新 | 不支持，使用 DSM 套件中心安装 SPK 更新 |
缺少“宿主机防火墙管理”不影响在 DSM 中手动配置防火墙规则；它表示 fn-knock 不会根据登录状态动态改写 DSM 防火墙。需要原始端口的直连授权时，应改用支持该能力的部署方式。
数据、日志与升级
运行数据、配置、证书和密钥保存在：
/var/packages/fn-knock-synology/var该目录包含敏感数据。升级前建议导出 fn-knock 应用备份，并把 DSM 的快照或备份策略纳入计划；不要在升级过程中手动清空此目录。服务日志默认位于：
/var/packages/fn-knock-synology/var/fn-knock.log.knock 应用归档便于迁移配置，DSM 目录快照则保留 SQLite、证书和套件运行数据。两者的范围不同，恢复顺序和导入版本限制见备份、恢复与数据清理。
DSM 原生套件不使用应用内 FPK 更新流程。获得新版本 SPK 后，在“套件中心 → 手动安装”中选择新文件完成升级；安装过程中服务会短暂重启。升级后重新从 DSM 主菜单进入管理界面，并验证网关、认证和一条已配置的业务映射。
启动流程会等待 Go 网关控制面可用，并在有限总时长内以逐步增加且有上限的间隔重试暂时性的连接拒绝、超时或 500 / 502 / 503 / 504；内存设置和完整 Host 规则成功下发后，应用才报告就绪。DSM 生命周期脚本的启动超时会传递给应用，避免脚本已经判定失败而后台仍继续初始化。持续出现 400、无效 Host 规则等永久配置错误时不会无限重试，应查看 fn-knock.log 中最早的启动同步错误并修正配置。
生命周期脚本会在停止或重启时终止 fn-knock 的整个独立进程组，并额外检查管理后端与 Go 网关 PID，避免父进程退出后留下子进程占用端口。若套件显示已停止但 7998 或 7999 仍被旧进程占用，先覆盖安装相同架构的最新 SPK 再从套件中心启动；不要反复安装不同架构的 SPK，也不要直接删除 PID 文件冒充已停止。
继续阅读：