使用 Docker 部署 Graft

在自己的服务器上运行 Eidos Lite 同步服务：启动容器，在服务器上生成私有初始化链接，再打开完整链接选择存储，Graft 会自动创建访问密钥。服务器根地址或单独的 /setup 均不是已授权的初始化入口。

本地磁盘配置最简单，也可以在浏览器中配置 S3 兼容存储。两种方式都需要在服务器上保留持久化磁盘空间。

开始前准备

一台 Linux AMD64 或 ARM64 服务器，已安装 Docker Engine 和 Compose v2 及 curl。
一个由已有代理或部署平台提供的 HTTPS 地址。没有代理时，可以使用下文可选的 Caddy 配置。
需要连接的电脑已安装 Eidos Lite 并激活 Spark，不需要官方 Sync 订阅。

**Caddy 是可选的。**将下文的 sync.example.com 替换为实际域名，命令在服务器上执行。

1. 下载并配置

为新安装创建私有目录，下载部署文件：

mkdir -m 700 ~/graft-sync
cd ~/graft-sync
curl -fL --retry 3 -o compose.yaml \
  https://github.com/eidos-space/graft/releases/download/graft-docker-v0.2.1/compose.yaml
cat > .env <<'EOF_ENV'
GRAFT_PUBLIC_ORIGIN=https://sync.example.com
EOF_ENV

该文件使用公开的 Graft Docker 0.2.1 镜像，通过摘要固定镜像内容。不需要登录 GitHub、下载源码或自行构建。填写不带路径的 HTTPS 地址，后续 Compose 命令均在这个目录中执行。

2. 接入 HTTPS

使用已有代理或部署平台

将 HTTPS 地址转发到服务器上的 http://127.0.0.1:8787。如果代理运行在另一个容器中，将它加入同一 Docker 网络，使用 http://graft:8787 作为上游。保持 8787 端口私有。代理需允许至少 64 MiB 请求体和至少 120 秒传输，原样转发路径和授权请求头，关闭 API 缓存。然后继续第 3 步。

可选：添加 Caddy

仅在需要代理时选择此项。将域名 DNS 指向服务器，开放 80 和 443 端口，并确认没有其他服务占用它们。

curl -fL --retry 3 -o compose.caddy.yaml \
  https://github.com/eidos-space/graft/releases/download/graft-docker-v0.2.1/compose.caddy.yaml
curl -fL --retry 3 -o Caddyfile \
  https://github.com/eidos-space/graft/releases/download/graft-docker-v0.2.1/Caddyfile
cat >> .env <<'EOF_ENV'
GRAFT_DOMAIN=sync.example.com
COMPOSE_FILE=compose.yaml:compose.caddy.yaml
EOF_ENV

GRAFT_DOMAIN 与 GRAFT_PUBLIC_ORIGIN 使用同一域名。 Caddy 会随 Graft 一起启动并管理证书，无需在宿主机安装或编辑系统文件。

3. 启动并打开设置

两条命令都要在服务器的 compose.yaml 所在目录中执行。 先获取初始化链接，再打开浏览器；不要直接打开根地址或手动输入 /setup 来配置存储。

docker compose up -d --wait
docker compose exec graft node services/graft-remote-docker/manage.mjs setup-link

在浏览器中打开 setup-link 输出的完整网址，包括 #token=… 部分。它指向公开地址下的 /setup，用于证明你能访问服务器终端，请勿分享整个链接。填写存储信息不能提供这项授权。如果 HTTPS 尚未就绪，检查 DNS 和代理日志后重试。

完成设置前，链接在重启后仍可使用。中途关闭页面后，重新执行相同命令即可取回。仅打开 /setup，没有链接中的初始化凭据，不能配置服务器。

4. 在浏览器中完成设置

选择本地磁盘即可继续，无需填写其他字段。使用 S3 兼容存储时，填写已有私有桶的信息：

字段	填写内容
S3 端点	服务商提供的 HTTPS S3 API 端点
区域	服务商指定的区域
存储桶名称	本次安装专用的已有桶，或其中包含独占前缀的桶
Access Key ID / Secret Access Key	限定到该桶的 S3 凭据

高级设置包含对象前缀（默认 graft/）、路径式寻址和可选会话令牌。使用以 / 结尾的独占前缀，并选择服务商支持的寻址方式。

使用 S3 时点击测试连接。Graft 会通过临时对象检查读、写、删除，有错误时先修正再继续。凭据还需允许分片上传，包括取消未完成的上传；启用版本控制的桶需要允许删除对象版本。连接测试不代表已验证大文件分片上传。避免配置妨碍有效对象使用和删除的保留、对象锁定或自动过期规则。

点击完成设置，将显示的服务器地址和访问密钥保存到密码管理器。该密钥可以访问这台服务器上的所有 Space，页面仅展示一次；遗失后可按下文取回。

密钥生成和配置保存会自动完成，无需在终端生成密码、创建密钥文件或修改文件权限。重启和升级不会重新开放初始化。

5. 连接 Lite

在 Lite 中打开同步 → 添加服务器，填写名称，粘贴服务器地址和访问密钥，选择测试并保存，再为 Space 选择该服务器并按照提示连接。详见连接自托管服务器。

服务器地址不要包含 /setup 或初始化凭据。 Space 同步密码与服务器访问密钥不同，用于加密和解锁 Space，两者都要保存。已有云端连接的 Space 请使用切换服务器，不要直接替换地址。

添加一条记录和一个小附件，在另一台电脑下载 Space，打开记录和附件，再修改记录，确认第一台电脑能收到更新。这样可以验证同步，而不只是健康检查正常。

日常维护

取回访问密钥

如果没有保存密钥，在服务器上执行：

docker compose exec graft node services/graft-remote-docker/manage.mjs access-key

该命令取回已有密钥，不会更换密钥或重新开放初始化。不要在截图或支持消息中包含密钥和初始化链接。

停止、重启和备份

在部署目录中使用 docker compose stop 和 docker compose start，保留文件和数据卷。 除非确实要删除本地安装数据，否则不要执行 docker compose down -v。 每个数据卷只运行一个 Graft 实例。

先暂停同步、停止 Graft，再备份：

**本地存储：**备份完整的 /data 数据卷，包括其中的私有配置。
**S3 存储：**在停止期间同时备份 /data 和对应桶内对象，缺少任意一份都无法完整恢复。S3 模式仍使用服务器磁盘保存元数据、上传分片和组装中的上传文件。
备份 Compose 文件、.env、外部管理的密钥，以及可选的 Caddy 证书数据。Space 同步密码另行保存。

妥善保护备份，网页配置中包含服务器密钥和 S3 凭据。在独立空数据卷中测试恢复，并通过客户端下载验证。对象存储本身不等于备份，同步操作可能删除对象。

升级已有安装

升级前先备份。将新版文件下载到独立目录，与现有安装比较，更新镜像引用和必要配置，保留数据卷、.env 和凭据，然后执行：

docker compose pull
docker compose up -d --wait

**从 0.1.1 升级：**保留已有 Compose 文件和挂载的访问密钥文件，将镜像引用更新为新版发布的摘要。已有外部密钥部署继续可用，并跳过网页初始化。直接替换为新版默认 Compose 会遗漏原密钥挂载；使用新模板管理外部密钥时，可以叠加发布附带的 compose.secrets.yaml。

修改存储模式、端点、桶名或前缀不会迁移数据。请使用全新存储部署另一台服务器，再通过 Lite 的切换服务器迁移。

S3 服务商示例

使用 Cloudflare R2 时，填写桶的 S3 端点，区域填写 auto，创建限定到桶的 S3 凭据，选择 **Object Read & Write（对象读写）**权限，而不是通用 API Token。使用 Backblaze B2 时，从桶详情复制端点和区域，创建限定到该桶的应用密钥： keyID 对应 Access Key ID，applicationKey 对应 Secret Access Key。

网页初始化已实测本地磁盘和 MinIO S3。R2 存储在上一服务版本中也经过实测； B2 属于配置示例，不代表已经完成真实 B2 验收。存储、请求和传输会产生服务商费用。

常见问题

现象	排查方法
容器无法启动	执行 `docker compose logs --tail=100 graft`，检查数据卷权限和磁盘空间。
初始化链接打不开	检查公开地址、DNS 和 HTTPS 代理；使用可选 Caddy 时查看 `docker compose logs --tail=100 caddy`。
测试连接／完成设置一直灰色不可用	在服务器的 Compose 目录中执行 `docker compose exec graft node services/graft-remote-docker/manage.mjs setup-link`，打开包含 `#token=…` 的完整输出。填写存储字段不能提供初始化授权。
初始化链接无效或不完整	从同一套安装重新取回链接。链接不会随时间过期，完成设置后才会失效；若已完成，使用上文的 `access-key` 命令。
页面拒绝提交	直接打开与 `GRAFT_PUBLIC_ORIGIN` 一致的 HTTPS 地址，不要跳转到其他来源。
页面显示设置已完成	使用保存的密钥，或执行 `access-key` 命令取回。
S3 测试失败	检查端点、区域、桶名、寻址方式和权限。若删除被拒绝，先清理残留的测试对象再重试。
设置前 `/healthz` 返回 503	属于预期行为，先完成设置。容器使用 `/livez` 检查进程，不代表同步已可用。
Lite 提示授权失败	填写服务器访问密钥，不要使用初始化凭据、S3 凭据或 Space 同步密码。