在非系统包管理（非 APT/YUM 等）环境下运行 Anki Sync Server 时，默认的数据存储位置与传统 Linux 目录结构往往不利于长期维护、迁移和备份。本文记录了一次将 Anki Sync Server 的数据目录从默认位置迁移并集中到应用目录下的实践过程，并总结了其中涉及的关键机制与注意事项，为需要“手动管理应用”的使用场景提供一种可复制的方案。
一、问题背景
Anki Sync Server 官方支持通过 Python 模块 anki.syncserver 运行同步服务。在默认配置下：
- 服务端数据存储在用户主目录下的隐藏目录中
- 数据路径由程序内部逻辑或环境变量决定
- 对于手动部署、非系统源更新的应用而言，这种分散式布局并不直观
在以下场景中，上述默认行为会带来不便：
- 应用不通过系统包管理器安装和更新
- 希望“一个应用 = 一个目录”，便于整体迁移
- 需要明确区分程序文件与数据文件
- 需要对备份、恢复和未来 Docker 化提前规划
因此，有必要将 Anki Sync Server 的数据目录显式迁移到应用自身目录中。
二、官方机制说明（关键前提）
根据 Anki 官方文档说明：
- 默认数据目录：
~/.syncserver - 可配置方式：通过环境变量
SYNC_BASE指定数据目录 - 重要限制：
- 服务端数据目录必须独立于客户端本地 Anki 数据目录
- 不允许通过手动复制客户端数据库来“初始化”服务端数据
- 正确方式是：客户端通过同步协议向服务端写入数据
这意味着，任何迁移方案都必须围绕 SYNC_BASE 这一官方支持的接口展开。
三、目标设计：应用自包含目录结构
迁移的目标并非简单“换路径”，而是形成一种清晰、稳定、可迁移的目录布局：
Anki/
├── bin/ # 应用自身运行环境（Python 等）
├── lib/ # 依赖库
├── anki.sh # 启动脚本
└── data/ # 同步服务器数据（SYNC_BASE 指向此处）
该结构具有以下特点：
- 程序与数据逻辑分离，但物理位置集中
- 整个应用目录可以整体备份或迁移
- 不依赖
/usr、/var等系统级目录 - 与 Linux FHS 保持最小耦合
四、迁移步骤概述
1. 停止同步服务
在任何数据操作之前，应先停止正在运行的同步服务，避免并发写入。
2. 准备目标数据目录
在应用目录下创建专用的数据子目录（例如 data/），并确保权限正确。
3. 迁移已有服务端数据
将默认数据目录中的内容整体迁移到新的数据目录中，保持原有目录层级（每个用户一个子目录）。
迁移完成后，新的结构应直接呈现为：
data/
├── <user_id_1>/
├── <user_id_2>/
└── ...
而不应再嵌套一层额外目录。
4. 修改启动脚本，显式指定 SYNC_BASE
启动脚本中通过环境变量明确指定数据路径，例如：
#!/bin/bash
set -e
APP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
export SYNC_BASE="$APP_DIR/data"
# 省略用户与网络相关环境变量配置
exec "$APP_DIR/bin/python" -m anki.syncserver
这里需要注意：
- 使用
BASH_SOURCE[0]而非$0，以避免在 systemd 或非交互环境中路径解析错误 - 不在脚本中隐式创建或重排数据目录，避免“自作聪明”的副作用
5. 启动服务并验证
重启服务后，通过以下方式确认迁移成功：
- 服务进程环境变量中存在正确的
SYNC_BASE - 新数据目录中有用户子目录产生更新
- 客户端能够正常完成同步
五、常见问题与经验总结
1. 多出一层目录的常见原因
若发现数据目录变为：
data/Anki_data/<user_id>/
通常意味着：
SYNC_BASE指向了上层目录- 实际数据又被人工或脚本放入了子目录
解决方式不是“改程序逻辑”，而是统一约定：SYNC_BASE 指向的目录，必须直接包含用户数据目录。
2. 不依赖当前工作目录（CWD）
Anki Sync Server 曾因未显式指定数据目录而依赖进程 CWD，这在 systemd 环境下可能默认为 /，造成数据位置混乱。通过 SYNC_BASE 可以完全规避这一问题。
3. 为什么不强行拆分为 /etc、/var
在手动管理应用、非系统源更新的前提下，遵循传统 FHS 往往增加维护成本。对这种应用而言，“应用自包含目录”比“系统级规范”更具工程可行性。
六、结语
通过官方支持的 SYNC_BASE 机制，将 Anki Sync Server 的数据迁移并集中到应用目录中，可以显著提升以下方面的可控性：
- 数据位置的确定性
- 备份与迁移的简洁性
- 长期手动维护的可读性
这种做法并非偏离官方设计，而是对官方机制在实际部署环境中的一次合理利用。对于不依赖系统包管理器的服务型应用而言，这是一种值得参考的实践模式。