必须同时部署syncserver和auth-server，因firefox sync v1.5协议将账户管理（注册/登录）与数据同步（上传/拉取）严格分离，二者通过oauth2 token通信，缺一则令牌签发或数据服务失败，导致401错误或同步中断。
必须同时部署 syncserver 和 auth-server，缺一不可；Firefox 客户端仅靠修改 about:config 中的三项 URI 就能强制切流，但前提是两个服务已 HTTPS 可达、CORS 白名单放行、且域名根证书可信。
syncserver 和 auth-server 为什么不能只跑一个
Firefox 同步协议在 v1.5 之后明确拆分为两层：账户生命周期（注册/登录/密码重置）由 auth-server 管理，而数据上传/拉取/加密分片则由 syncserver 承担。两者通过 OAuth2 Bearer Token 通信——syncserver 启动时会向 auth-server 的 /v1/cert/sign 接口请求签名证书，若失败则直接拒绝启动，并在日志中输出 Failed to fetch certificate from auth server。
常见错误现象包括：
- 客户端在 about:config 修改完所有地址后，仍弹出“无法连接到账户服务”提示
- 同步日志（
about:sync-log）中反复出现TokenServer returned 401或No token found for user -
syncserver进程启动成功，但curl -I https://sync.example.com/token/1.0/sync/1.5返回 500 或空响应
根本原因几乎全是 auth-server 不可用或二者域名不匹配。比如 syncserver 的 public_url 设为 https://sync.example.com，而 auth-server 监听在 https://auth.internal.lan，即使加了 CORS 头，Firefox 也会因跨域证书链断裂而终止握手。
about:config 里哪三项 URI 必须改，顺序和值怎么核对
这三项不是可选配置，而是 Firefox 客户端硬编码的 fallback 地址。只要其中任意一项未覆盖，浏览器就会回退到 Mozilla 公共基础设施，完全无视你本地部署的服务。
必须逐项检查并双击修改为你的实际服务地址：
-
identity.fxaccounts.autoconfig.uri→ 值设为auth-server的根 URL，例如https://auth.example.com -
identity.sync.tokenserver.uri→ 值设为syncserver的完整 token 接口路径，例如https://sync.example.com/token/1.0/sync/1.5（注意末尾斜杠和版本号） -
identity.fxaccounts.remote.root→ 值必须与autoconfig.uri一致，即https://auth.example.com
容易踩的坑：
- 漏掉
https://前缀，导致 Firefox 拒绝加载（HTTP 被强制降级拦截） - 在
tokenserver.uri中写成https://sync.example.com/token（少后缀），会返回 404，且无明确错误提示 - 修改后未彻底关闭 Firefox 进程（macOS 上常驻后台，Windows 任务栏右键退出不等于杀进程），导致配置不生效
Docker 部署 syncserver 时哪些环境变量不能省
Docker 是目前最稳妥的部署方式，但镜像本身不带默认配置，所有关键参数必须通过 -e 显式传入，否则容器会立即退出并报错 Missing required configuration: SYNCSERVER_PUBLIC_URL。
必须设置的环境变量有：
-
SYNCSERVER_PUBLIC_URL：完整 HTTPS 地址，如https://sync.example.com -
SYNCSERVER_SECRET：32 字节 Base64 随机密钥，用openssl rand -base64 32生成，不能复用或留空 -
SYNCSERVER_SQLURI：数据库连接串，SQLite 示例为sqlite:////data/sync.db，MySQL 示例为mysql+pymysql://user:pass@db-host/sync
额外建议：
- 用
-v /host/path:/data挂载宿主机目录，避免 SQLite 文件随容器销毁丢失 - 不要依赖镜像内置的
gunicorn默认 worker 数，高并发场景下需加--workers 4 --threads 2参数 - 容器日志里看到
Listening on http://0.0.0.0:5000不代表就绪，必须再curl -I https://sync.example.com/__heartbeat__确认返回 200
桌面端注册账户为什么不能用手机 Firefox 扫码完成
自建服务环境下，Firefox 官方的扫码登录流程（fx_desktop_v3 协议）默认指向 Mozilla 的 accounts.firefox.com，不会读取你改过的 about:config 配置。也就是说，手机端扫码本质是向官方 auth-server 发起 OAuth 请求，和你本地部署的服务完全无关。
必须用桌面端 Firefox 浏览器访问 https://auth.example.com（即你配置的 identity.fxaccounts.autoconfig.uri），手动填写邮箱、密码完成注册。注册成功后，该账户才被写入你本地的 auth-server 数据库，并能被 syncserver 识别。
验证是否注册成功的方法：
- 在
auth-server日志中搜索POST /v1/account/create是否返回 200 - 用
curl -X POST https://auth.example.com/v1/account/login -d '{"email":"you@example.com","password":"xxx"}'看能否拿到 sessionToken - 登录后立刻打开
about:sync-log，首次同步应显示First sync completed而非反复重试
整个过程没有图形化注册页，也没有“跳过邮箱验证”选项——这是设计使然，不是 bug。如果你跳过了这一步，后续所有设备都无法登录，因为账户根本不存在于你的私有 auth-server 中。
