any-sync-bundle 部署笔记：外部地址首启就写死、备份要等干净停止、老 CPU 跑 AIO 会直接 illegal instruction

项目信息

• 仓库：github.com/grishy/any-sync-bundle
• Release 页：github.com/grishy/any-sync-bundle/releases
• 镜像：ghcr.io/grishy/any-sync-bundle:1.7.0-2026-10-12、ghcr.io/grishy/any-sync-bundle:1.7.0-2026-10-12-minimal
• 作者 grishy，MIT 许可，Go 编写

当前版本 v1.7.0-2026-10-12，版本号格式是 v[bundle-version]-[anytype-compatibility-date]，1.x 之间 bundle 配置格式保持可读，跨小版本升级不需要重建配置。

它是什么，以及什么情况下别用

any-sync-bundle 把 Anytype 官方同步所需的全部模块合进一个二进制，作者自己的说法是 “K3s for Any Sync”，即 All-in-One 单进程部署。对外只开两个端口：

• TCP 33010 — DRPC 协议
• UDP 33020 — QUIC 协议

不适用的情况很明确：需要多节点高可用集群、需要单机之外的水平扩展、想按官方 Anytype 架构原样拆开部署。这三类需求直接看官方组件，别在这里绕。

一键启动

docker run

docker run -d \
  -e ANY_SYNC_BUNDLE_INIT_EXTERNAL_ADDRS="192.168.100.9" \
  -p 33010:33010 \
  -p 33020:33020/udp \
  -v $(pwd)/data:/data \
  --stop-timeout 120 \
  --restart unless-stopped \
  ghcr.io/grishy/any-sync-bundle:1.7.0-2026-10-12

--stop-timeout 120 不是可选项。停止时进程要按顺序关闭内部组件，超时太短会被 SIGKILL 打断，落盘状态就不完整了。

首次运行后，把 ./data/client-config.yml 导入 Anytype 客户端即可。

Compose

仓库给了四份 compose 文件，对应四种形态：

docker compose -f compose.aio.yml up -d

启动前必须先改 compose 里的 ANY_SYNC_BUNDLE_INIT_EXTERNAL_ADDRS，这一步漏了会掉进下一节的坑。

二进制方式

二进制只支持外部 MongoDB / Redis，不带内置存储：

./any-sync-bundle start-bundle \
  --initial-external-addrs "192.168.100.9" \
  --initial-mongo-uri "mongodb://127.0.0.1:27017/" \
  --initial-redis-uri "redis://127.0.0.1:6379/" \
  --initial-storage ./data/storage

两个启动命令的区别：start-bundle 连外部 Mongo/Redis，start-all-in-one 用内置的，容器里跑的就是后者。

外部地址这一项到底影响什么

所有 ANY_SYNC_BUNDLE_INIT* 变量只在启动时读一次，随后被烘焙进 ./data/bundle-config.yml。其中只有 ANY_SYNC_BUNDLE_INIT_EXTERNAL_ADDRS 是必填项（通告地址），它会被写进配置的 externalAddr: 列表，客户端拿到的连接信息就来自这里。

这意味着：第一次启动填了 192.168.100.9，之后你把环境变量改成域名或公网 IP 再重启，不会生效——配置已存在，初始化逻辑不会覆盖。典型表现是容器正常起来、日志无报错、防火墙也放行了，但客户端导入配置后一直连不上，因为客户端还在往那个旧地址发包。

修法是直接改配置文件，不是改环境变量：

1. 编辑 ./data/bundle-config.yml 里的 externalAddr: 列表
2. 重启服务
3. 重启时 client-config.yml 会按新地址重新生成，客户端需要重新导入

改地址前先把这条想清楚：这个值应该是客户端视角能到达的 IP 或域名，不是容器内网地址。

客户端导入 client-config.yml

两个配置文件性质完全不同：

• ./data/bundle-config.yml — 服务配置 + 私钥，必须备份，丢了等于身份丢了
• ./data/client-config.yml — 每次启动重新生成，不用备份

把后者导入 Anytype 客户端。地址一改，这份文件就作废，得重新导入。

存储与 S3

默认存储是内置 BadgerDB：零配置、延迟低，上限受本地磁盘限制。对单机自用够了。

要横向扩或者数据量超本地磁盘，可选 S3，走的是 any-sync-filenode 上游实现，支持 AWS S3、MinIO、DigitalOcean Spaces、Cloudflare R2、Backblaze B2。代价是网络延迟和额外的配置量。

相关环境变量：

对应命令行参数是 --initial-s3-force-path-style（MinIO 要加）和 --initial-s3-region（自定义 region 时加）。

compose.s3.yml 里的 MinIO 是社区构建，按 digest 固定。控制台在 http://localhost:9001，账号密码 minioadmin / minioadmin，上线前记得改。

全局参数与启动参数

全局参数：

• --debug / ANY_SYNC_BUNDLE_DEBUG
• --log-level：debug、info、warn、error、fatal，默认 info
• --pprof：默认 false，监听 localhost:6060

启动参数及默认值：

• --bundle-config / -c → ./data/bundle-config.yml
• --client-config / --cc → ./data/client-config.yml
• --initial-storage → ./data/storage/
• --initial-external-addrs → 192.168.8.214,example.local（可逗号分隔多个）

备份与升级的操作顺序

备份

只在干净停止之后备份。 运行中直接打包大概率拿到不一致的 MongoDB 状态，恢复时起不来或数据缺失。停止后等日志出现 bundle_shutdown_complete 再动手：

docker compose -f compose.aio.yml stop
# 确认日志出现 bundle_shutdown_complete
tar --exclude='./data/mongo/diagnostic.data' -czf backup-$(date +%Y%m%d-%H%M%S).tar.gz ./data/

mongo/diagnostic.data 是诊断信息，不是数据库状态，排除掉能省不少体积。

恢复：

rm -rf ./data && tar -xzf backup-YYYYMMDD-HHMMSS.tar.gz

升级

1. 备份 ./data/
2. 停止服务
3. docker pull 新镜像
4. 启动
5. 看日志和 --version 输出

失败就回滚到备份加旧版本，两步都要做，只回滚版本不回滚数据可能对不上。

故障排查

开发相关：构建见 CONTRIBUTING.md，flake.nix 可以拉起开发环境。许可证 MIT。