NixOS 上部署 Anki Sync Server：内置同步服务模块配置与源码级原理详解

包管理器操作系统【免费下载链接】nixpkgsNix Packages collection NixOS项目地址https://gitcode.com/GitHub_Trending/ni/nixpkgs点击查看免费下载导读本文围绕 NixOS 仓库中的services.anki-sync-server系统模块展开介绍如何用声明式配置在 NixOS 上快速部署 Anki 官方内置的同步服务器Anki Sync Server用它替代 AnkiWeb 完成卡组数据的自托管同步。读完本文你将掌握该模块的全部配置项用户凭证、存储目录、监听地址与防火墙、理解其基于 systemdDynamicUser与 credential 机制的底层实现并通过集成测试了解如何验证同步链路可用。背景什么是 Anki Sync ServerAnki Sync Server 是随新版 Anki 客户端内置的官方同步服务器实现。对于无法或不想使用 AnkiWeb 云同步的高级用户可以直接在自有服务器上运行该同步服务让 Anki 客户端的同步流量完全掌握在自己手中。NixOS 仓库通过nixos/modules/services/misc/anki-sync-server.nix提供了services.anki-sync-server这一系统模块将 Anki 内置的同步服务封装为开箱即用的 systemd 服务。版本兼容性要求该模块只兼容 Anki 版本 2.1.66原因是 Nix 的 anki 包在此版本之后才内置了同步服务器相关的增强该模块基于 NixOS/nixpkgs 提交05727304f8815825565c944d012f20a9a096838a引入。当前仓库中 anki 包版本为26.08见 pkgs/by-name/an/anki/package.nix远高于最低要求可放心使用。快速开始启用服务默认情况下模块会创建一个 systemd 单元以 systemdDynamicUser选项创建一个隔离的系统用户来运行同步服务器。在 NixOS 配置中启用该服务只需设置{ ... }: { services.anki-sync-server.enable true; }模块通过mkEnableOption注册services.anki-sync-server.enable选项见 模块源码并在 nixos/modules/module-list.nix 中被列入默认模块列表因此无需额外imports即可使用。仅开启enable还不够——模块在配置求值期就通过assertions强制要求至少配置一个用户名-密码对否则 NixOS 会在构建/切换配置时报错assertions [ { assertion (builtins.length usersWithIndexesFile) (builtins.length usersWithIndexesNoFile) 0; message At least one username-password pair must be set in services.anki-sync-server.users.; } ];配置同步用户users 详解模块要求显式声明至少一个用户名-密码对配置在services.anki-sync-server.users列表下{ services.anki-sync-server.users [ { username user; passwordFile /etc/anki-sync-server/user; } ]; }每个用户条目是一个 submodule包含以下三个选项源码定义见 模块 options 段选项类型默认值说明usernamestr无必填同步服务器接受登录的用户名passwordnullOr strnull该用户名对应的密码passwordFilenullOr pathnull存放该用户名密码的文件路径password vs passwordFile两种密码提供方式password明文直写直接在 Nix 配置中书写密码。模块源码对此有明确的WARNING该密码会以明文形式存储并且对所有用户可见因为它会进入 Nix store 与世界共享的 systemd environment。因此仅适用于测试或非敏感环境生产使用应优先选择passwordFile。passwordFile凭据文件指向一个只包含纯文本密码的文件。模块注释明确要求务必设置权限使该文件除 root 外的任何用户都不可读。这是推荐的更安全方式。{ services.anki-sync-server.users [ { username alice; password dev-only-password; } { username bob; passwordFile /etc/anki-sync-server/bob; } ]; }两个选项可以混合使用如上面例子所示模块会分别处理这两类用户。底层实现passwordFile 走 systemd credential从模块源码的启动脚本anki-sync-server-run模块源码 L20-L37可以看出两种方式的分流处理设置了passwordFile的用户其密码文件会通过 systemd 单元的LoadCredential以 credential 形式挂载进服务文件系统$CREDENTIALS_DIRECTORY启动脚本用read -r pass ${CREDENTIALS_DIRECTORY}/username读取后以SYNC_USER1username:password形式导出为环境变量设置了password的用户密码被直接以SYNC_USERNusername:password形式写进环境变量明文。最终所有用户凭证都以SYNC_USER序号环境变量的形式传递给 Anki 同步服务器本体exec ${lib.getExe cfg.package}。这正是模块文档要求passwordFile文件仅 root 可读的原因它会被作为敏感凭据挂载而非写入全局可见的 Nix store。数据存储目录baseDirectory默认情况下同步数据存储在/var/lib/anki-sync-server/下对应每个用户一个子目录模块文档描述为ankiuser目录。该默认值来自模块的baseDirectory选项baseDirectory mkOption { type types.str; default %S/%N; description Base directory where user(s) synchronized data will be stored.; };这里%S/%N是 systemd 规范说明符%S展开为StateDirectory指定的状态目录配合StateDirectory name即/var/lib/anki-sync-server%N是单元名。该值最终通过SYNC_BASE环境变量注入服务。如需更改存储位置设置services.anki-sync-server.baseDirectory{ services.anki-sync-server.baseDirectory /home/anki/data; }同步数据各用户的 Anki 集合数据库将存储在该目录下对应各用户的子目录中。网络监听address / port / openFirewall默认情况下服务器监听地址services.anki-sync-server.address为回环地址监听端口services.anki-sync-server.port并且不会开放防火墙。这一组合适合纯本机测试或置于反向代理之后使用。注意源码中的默认值与选项名细节模块 options 段address mkOption { type types.str; default ::1; description IP address anki-sync-server listens to. Note host names are not resolved. ; }; port mkOption { type types.port; default 27701; description Port number anki-sync-server listens to.; };address默认::1IPv6 回环类型是纯字符串且不支持主机名解析只能填 IP 地址port默认27701类型为types.port取值范围即合法端口范围openFirewall布尔值默认false开启时模块会将port加入networking.firewall.allowedTCPPorts见 模块 L114。如果需要把同步服务器直接暴露给其他电脑大多数情况下不推荐因为同步服务器本身不使用 HTTPS明文传输凭证与数据可以按模块文档给出的方式配置{ services.anki-sync-server.address 0.0.0.0; services.anki-sync-server.openFirewall true; }更稳妥的落地方式是保持默认回环监听 openFirewall false在前面接 Nginx/Caddy 等反向代理终止 TLS。模块在配置求值时会通过specEscapereplaceStrings [ % ] [ %% ]把地址中的%转义为%%避免与 systemd 规范说明符冲突随后写入SYNC_HOST环境变量。运行机制systemd 单元与隔离模块生成的 systemd 单元关键配置如下模块 L116-L137systemd.services.anki-sync-server { description anki-sync-server: Anki sync server built into Anki; after [ network.target ]; wantedBy [ multi-user.target ]; path [ cfg.package ]; environment { SYNC_BASE cfg.baseDirectory; SYNC_HOST specEscape cfg.address; SYNC_PORT toString cfg.port; }; serviceConfig { Type simple; DynamicUser true; StateDirectory name; ExecStart anki-sync-server-run; Restart always; LoadCredential map ( x: ${specEscape x.user.username}:${specEscape (toString x.user.passwordFile)} ) usersWithIndexesFile; }; };值得关注的安全与运维设计DynamicUser true服务运行时动态分配一个一次性系统用户无需在 NixOS 中预创建用户进程以隔离身份运行最小化权限面StateDirectory anki-sync-server自动创建/var/lib/anki-sync-server状态目录并赋予正确属主Restart always进程异常退出后由 systemd 自动拉起LoadCredential将passwordFile以 credential 形式安全传递给服务见上文底层实现Type simpleExecStart直接以前台方式运行同步服务器进程经由启动脚本设置好SYNC_USER*环境变量后exec到cfg.package的可执行文件。模块还提供services.anki-sync-server.package选项mkPackageOption pkgs anki-sync-server默认即 anki 包内置的同步服务器二进制如需替换实现例如自编译或特定版本可覆盖该选项。验证集成测试如何证明同步可用仓库为这个模块提供了完整的 NixOS 集成测试nixos/tests/anki-sync-server.nix并在 nixos/tests/all-tests.nix 中以anki-sync-server runTest ./anki-sync-server.nix;注册同时通过 anki 包的passthru.tests.anki-sync-serverpkgs/by-name/an/anki/package.nix关联到包本身。测试机器的配置同时覆盖了两种密码提供方式services.anki-sync-server { enable true; users [ { username user; password password; } { username passfileuser; passwordFile testPasswordFile; } ]; };测试脚本的执行逻辑验证了关键行为服务可启动等待anki-sync-server.service进入运行状态并等待27701端口开放错误凭证被拒绝用baduser/badpass调用sync_login预期抛出anki.errors.SyncError坏登录必须失败正确凭证可登录分别用user/password与passfileuser/passfilepassword登录成功验证了password与passwordFile两条路径都工作同步链路可达登录后调用col.sync_collection(login, False)断言sync.required sync.NO_CHANGES证明客户端与服务器之间完成了真实同步握手。测试还揭示了同步服务器的 Python 环境细节测试脚本通过将pkgs.anki.lib/${python3.sitePackages}加入sys.path来复用 anki 的 Python 库anki.collection因为 anki 是以buildPythonApplication构建的anki.lib并非正规 Python 库。从旧方案迁移ankisyncd 已被取代如果你是从旧版 NixOS 升级而来需要注意命名与包层面的变更NixOS 23.11 时代曾引入独立的 Rust 实现anki-sync-server-rs后在 24.05 中被 Anki 官方内置同步服务器取代见 rl-2405.section.md 中该模块的引入说明旧式 Python 实现ankisyncd及其services.ankisyncd选项已在后续版本中移除见 rl-2411.section.md模块还内置了重命名兼容逻辑nixos/modules/rename.nix 会把旧配置services.ankisyncd自动映射并给出替换提示services.anki-sync-server。因此新部署直接使用services.anki-sync-server即可旧配置则需改写为本文所述的选项结构。总结一条可落地的部署路径综合文档、模块源码与集成测试推荐的 NixOS 部署形态是{ ... }: { services.anki-sync-server { enable true; users [ { username me; passwordFile /etc/anki-sync-server/me; } ]; # 保持默认监听 ::1:27701不开防火墙由反向代理终止 TLS }; }再配合 Nginx/Caddy 将/sync/等路径反代到127.0.0.1:27701即可让 Anki 客户端通过自有域名完成加密同步既绕开 AnkiWeb又避免明文直连互联网的风险。该模块的全部选项定义集中在 nixos/modules/services/misc/anki-sync-server.nix集成验证可参考 nixos/tests/anki-sync-server.nix两者共同构成了理解和使用该服务的最佳起点。赞分享包管理器操作系统【免费下载链接】nixpkgsNix Packages collection NixOS项目地址https://gitcode.com/GitHub_Trending/ni/nixpkgs点击查看免费下载相关推荐NixOS Livebook 模块实战用户服务部署、environmentFile 安全配置与源码级原理NixOS Livebook 模块实战用户服务部署、environmentFile 安全配置与源码级原理 本文基于 NixOS 官方 Livebook 模块文包管理器操作系统离线也能用的桌面画图工具drawio-desktop 三条上手路径离线也能用的桌面画图工具drawio desktop 三条上手路径 内网断外网、公司电脑没管理员权限、画图软件的授权还没批下来——这是让绘图工具最尴尬的三种环桌面应用图形学NixOS 模块实战自建 Firefox Sync 同步服务器firefox-syncserverNixOS 模块实战自建 Firefox Sync 同步服务器firefox syncserver 本文基于 NixOS 官方模块文档 firefox s包管理器操作系统上一篇AI2PSD实战指南5步解决Illustrator到Photoshop的转换难题下一篇webpack universal target 全平台通用构建实战单份源码、一份 ESM Bundle 跑通浏览器 / Node.js / Deno / Bun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考