部署与配置

在稳定版 v0.11.0 上持久化运行 Depsilo，并配置就绪检查、诊断与备份恢复。

状态	容器内路径	说明
配置	`/root/.depsilo/config.toml`	首次设置生成；包含运行配置，可能包含敏感值
SQLite	`/root/.depsilo/data/depsilo.db`	用户、策略、审计记录和缓存元数据的权威状态
本地对象缓存	`/root/.depsilo/data/cache`	包制品；不包含在 `depsilo backup` 归档中

使用单个可执行文件

新安装可以使用 Linux 或 macOS 的 amd64 / arm64 二进制包。下面的 POSIX shell 脚本按当前系统选择稳定版资产，核对 SHA-256 后安装到 ~/.local/bin/depsilo；需要 curl、tar 以及 sha256sum 或 macOS 自带的 shasum。已有实例请先按对应版本的升级流程备份状态。

(
  set -eu
  case "$(uname -s)" in
    Linux) depsilo_os=linux ;;
    Darwin) depsilo_os=darwin ;;
    *) printf 'Use the Windows archive from the release page.\n' >&2; exit 1 ;;
  esac
  case "$(uname -m)" in
    x86_64|amd64) depsilo_arch=amd64 ;;
    aarch64|arm64) depsilo_arch=arm64 ;;
    *) printf 'Unsupported CPU architecture.\n' >&2; exit 1 ;;
  esac
  depsilo_archive="depsilo_0.11.0_${depsilo_os}_${depsilo_arch}.tar.gz"
  depsilo_release='https://github.com/depsilo/depsilo/releases/download/v0.11.0'
  depsilo_download_dir=$(mktemp -d "${TMPDIR:-/tmp}/depsilo-install.XXXXXX")
  trap 'rm -rf "$depsilo_download_dir"' EXIT
  cd "$depsilo_download_dir"
  curl -fSL "$depsilo_release/$depsilo_archive" -o "$depsilo_archive"
  curl -fSL "$depsilo_release/checksums.txt" -o checksums.txt
  awk -v archive="$depsilo_archive" '$2 == archive' checksums.txt > selected.sha256
  test -s selected.sha256
  if command -v sha256sum >/dev/null 2>&1; then
    sha256sum -c selected.sha256
  else
    shasum -a 256 -c selected.sha256
  fi
  tar -xzf "$depsilo_archive" depsilo
  mkdir -p "$HOME/.local/bin"
  install -m 0755 depsilo "$HOME/.local/bin/depsilo"
)

资产名为 depsilo_0.11.0_linux_amd64.tar.gz 等；Windows 的 ZIP 包和全部校验文件见 v0.11.0 发布页。需要签名验证时，按发布验证说明校验。

在前台启动服务，保留这个终端以读取引导令牌：

cd "$HOME"
"$HOME/.local/bin/depsilo" version
"$HOME/.local/bin/depsilo" serve --host 127.0.0.1 --port 23333

打开 http://localhost:23333 完成首次设置，再在另一个终端执行快速开始中的就绪检查和第一条请求。无需先配置 HTTPS。新安装未指定配置文件时，首次设置将配置、数据库和本地缓存保存在运行用户的 ~/.depsilo/；只运行一个进程使用这份状态。按 Ctrl+C 停止，再运行同一条 serve 命令即可恢复。长期运行时，由服务管理器保持相同用户与配置路径。

为其他设备配置 HTTPS

本机验证直接使用 http://127.0.0.1:23333。需要让其他设备通过 HTTPS 接入时，可以在同一台 Linux 主机上运行 Caddy，将请求转发给 Depsilo 的回环 HTTP 端口。以下示例假定 Caddy 是客户端直接连接的入口；已有 CDN 或其他代理时，需另行配置代理信任链。

让 Depsilo 的后端端口只在本机可达。 二进制使用上面的 --host 127.0.0.1。如果已按快速开始创建 Docker 容器，下面的命令会短暂停止服务并以回环端口重新创建容器，继续使用原来的 depsilo-state 命名卷；只适用于该卷名和挂载布局，其他布局先调整为自己的原有挂载。

docker stop depsilo
docker rm depsilo
docker run -d --name depsilo --restart unless-stopped \
  -p 127.0.0.1:23333:23333 \
  -v depsilo-state:/root/.depsilo \
  ghcr.io/depsilo/depsilo:0.11.0

准备域名与 Caddy。 按 Caddy 官方安装说明在这台 Linux 主机上安装带 systemd 服务的 Caddy。将自己的域名 A/AAAA 记录指向主机，保证证书校验所需的 80/443 端口可达，并保留 Caddy 的证书数据目录。将下面的 depsilo.example.com 换成自己的域名，加入 /etc/caddy/Caddyfile，保留该文件中其他站点的配置：

depsilo.example.com {
  reverse_proxy 127.0.0.1:23333 {
    header_up Host {hostport}
  }
}

这段配置保留客户端访问的 Host，并由 Caddy 设置 X-Forwarded-Proto，让 Depsilo 返回正确的 HTTPS 制品地址。公网域名满足条件后，Caddy 会申请并续期证书；内网域名需要内部 CA，并让每个客户端信任该 CA。参见 Caddy 自动 HTTPS与反向代理头部说明。

校验并加载配置。 以下命令针对已运行的官方 caddy systemd 服务；首次启用服务时按 Caddy 服务指南启动。

sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

从客户端检查 HTTPS 入口。 替换域名后运行，不使用跳过证书校验的选项：

DEPSILO_URL='https://depsilo.example.com'
curl -fsS "$DEPSILO_URL/ready"
curl -fsS "$DEPSILO_URL/npm/is-number" -o /dev/null -w 'HTTP %{http_code}\n'

收到 HTTP 200 后，在同一 HTTPS 地址的 Admin → Access logs 找到本次 is-number 请求，再按验证缓存检查返回的制品地址及实际下载。最后将客户端源地址设为这个 HTTPS 入口。

server.trusted_proxies 控制转发客户端 IP 的信任范围，默认不信任代理。需要记录原始客户端 IP 时，只添加 Depsilo 实际看到的代理地址；宿主机代理经 Docker 转发时不一定表现为 127.0.0.1。这项配置不代替 Host / X-Forwarded-Proto 转发，也不应为了显示客户端 IP 而信任所有地址。

配置来源与优先级

v0.11.0 按以下顺序解析同一个配置项，左侧优先级最高：

CLI 参数
DEPSILO_* 环境变量
config.toml
内置默认值

例如 server.port 对应 DEPSILO_SERVER_PORT，cache.ttl_index 对应 DEPSILO_CACHE_TTL_INDEX。可用 DEPSILO_CONFIG 指定配置文件；未指定时依次搜索 ./config.toml、/app/config.toml 和 ~/.depsilo/config.toml。

下表只列出部署时最容易混淆的值：

配置项	v0.11.0 内置默认值	v0.11.0 样例文件	生产建议
`server.host`	`127.0.0.1`	`0.0.0.0`	官方容器通过 `DEPSILO_SERVER_HOST=0.0.0.0` 监听；二进制部署按需放开，或交由 TLS 反向代理保护
`server.port`	`23333`	`23333`	端口可改，但探针和客户端地址必须同步
`database.dsn`	`./data/depsilo.db`	`./data/depsilo.db`	容器中使用卷内绝对路径
`storage.path`	`./data/cache`	`./data/cache`	容器中使用卷内绝对路径
`cache.max_size_gb`	`20`	`20`	按制品规模和磁盘预算调整
`cache.ttl_index`	`5m`	`1h`	根据元数据新鲜度要求选择
`cache.ttl_blob`	`72h`	`72h`	与容量和离线容忍度一起评估
`auth.enabled`	`true`	`true`	对管理面保持启用
`auth.token_ttl`	`168h`	`168h`	按组织会话策略缩短

当没有找到配置文件时，v0.11.0 会把数据库和缓存的实际默认路径迁到 ~/.depsilo/data/ 下，并为设置流程生成临时安全的 JWT secret。这是“无配置文件”的特殊行为，不会让样例文件中的占位符变安全。

如果使用显式配置文件，监听非 loopback 地址时，auth.jwt_secret = "change-me-in-production" 会导致启动失败。用秘密管理系统注入随机值，例如：

export DEPSILO_AUTH_JWT_SECRET="$(openssl rand -hex 32)"

不要把 secret 提交到仓库，也不要通过公开日志传递。

上游配置由谁负责

首次升级或启用普通包生态时，Depsilo 会把普通上游种子导入数据库。导入后，Admin 界面和数据库是这些上游的权威来源，重启不会把删除或修改的上游恢复成配置文件内容。为此前未启用的受支持生态添加配置，可在下次重启时激活它。

Docker registry 和 extra index 仍由配置文件管理，不能通过普通的 Admin Upstream CRUD 来维护。自动化部署应区分这两类来源，避免把配置文件当作所有运行状态的持续同步源。

就绪检查与诊断

/ready 会检查 SQLite 和对象存储；任一不可用时返回非 2xx。它故意不检查上游，因为上游中断时 Depsilo 仍可能提供已有缓存。

curl -fsS http://127.0.0.1:23333/ready

docker exec depsilo /app/depsilo doctor
docker exec depsilo /app/depsilo doctor --json

Docker 镜像自身的健康检查也使用 /ready。在编排平台中，用它决定实例是否接收流量； /health 只适合作为进程存活信号。doctor 还会检查版本、存储、上游和缓存命中情况。未提供 DEPSILO_TOKEN 时，受保护的管理详情会减少，但基础诊断仍可运行。

备份与恢复

depsilo backup 可在服务运行时创建一致的 SQLite 快照。先把归档写入状态卷，再复制到容器外的受控备份位置：

docker exec depsilo mkdir -p /root/.depsilo/backups
docker exec depsilo /app/depsilo backup \
  --out /root/.depsilo/backups/depsilo-backup.tar.gz
docker cp depsilo:/root/.depsilo/backups/depsilo-backup.tar.gz .

归档只包含 config.toml 文件和一致的 SQLite 快照，不包含本地或 S3 缓存对象。它含有用户、策略、审计和可能的秘密配置，应加密、限制访问并复制到故障域之外。缓存需要单独保护，或接受恢复后从上游重新获取。

在普通 Linux Docker 中，docker cp 导出的归档通常归执行复制的宿主用户所有，而 depsilo backup 生成的文件权限为 0600。如果宿主文件所有者不是镜像内的 10001:10001，直接只读挂载宿主目录可能让默认非 root 恢复进程无法读取归档；这不是所有 Docker 环境都必现的问题。

下面的命令适用于本页的 depsilo 容器和 depsilo-state 命名卷，在存放归档的目录执行。脚本先检查归档、运行中的容器及镜像版本，再新建独立的临时输入卷。仅辅助容器以 root 身份复制归档并设置所有权；输入卷目录保持 0700、归档保持 0600。随后用镜像默认的非 root 身份从只读卷检查权限和可读性。这些准备步骤成功后才会停止服务；实际 restore 仍使用镜像默认身份，恢复生成的状态文件由该身份拥有。若准备失败，脚本不会停止服务，并尝试删除本次创建的临时卷。复制到卷前请确保宿主归档的来源和内容可信。

sh -eu <<'RESTORE'
image='ghcr.io/depsilo/depsilo:0.11.0'
archive="$PWD/depsilo-backup.tar.gz"
if ! test -f "$archive" || ! test -r "$archive"; then
  echo 'Backup archive is missing or unreadable; aborting.' >&2
  exit 1
fi
test "$(docker inspect --format '{{.State.Running}}' depsilo)" = true
test "$(docker inspect --format '{{.Image}}' depsilo)" = \
  "$(docker image inspect --format '{{.Id}}' "$image")"
test "$(docker inspect --format '{{range .Mounts}}{{if and (eq .Type "volume") (eq .Destination "/root/.depsilo")}}{{.Name}}{{end}}{{end}}' depsilo)" = depsilo-state

input_volume="depsilo-restore-input-$(date +%s)-$$"
if docker volume inspect "$input_volume" >/dev/null 2>&1; then
  echo 'Input volume already exists; aborting.' >&2
  exit 1
fi
docker volume create "$input_volume" >/dev/null
trap 'docker volume rm "$input_volume" >/dev/null || true' 0

docker run --rm --user 0:0 --entrypoint /bin/sh \
  -v "$archive:/source/depsilo-backup.tar.gz:ro" \
  --mount "type=volume,src=$input_volume,dst=/backup" \
  "$image" -ec '
    cp /source/depsilo-backup.tar.gz /backup/depsilo-backup.tar.gz
    chown 10001:10001 /backup /backup/depsilo-backup.tar.gz
    chmod 0700 /backup
    chmod 0600 /backup/depsilo-backup.tar.gz
  '
docker run --rm --entrypoint /bin/sh \
  --mount "type=volume,src=$input_volume,dst=/backup,readonly" \
  "$image" -ec '
    test "$(id -u):$(id -g)" = 10001:10001
    test "$(stat -c "%u:%g:%a" /backup)" = 10001:10001:700
    test "$(stat -c "%u:%g:%a" /backup/depsilo-backup.tar.gz)" = 10001:10001:600
    test -r /backup/depsilo-backup.tar.gz
    test -s /backup/depsilo-backup.tar.gz
  '
trap - 0

docker stop depsilo
docker run --rm \
  -v depsilo-state:/root/.depsilo \
  --mount "type=volume,src=$input_volume,dst=/backup,readonly" \
  -e DEPSILO_CONFIG=/root/.depsilo/config.toml \
  -e DEPSILO_DATABASE_DSN=/root/.depsilo/data/depsilo.db \
  -e DEPSILO_STORAGE_PATH=/root/.depsilo/data/cache \
  "$image" restore /backup/depsilo-backup.tar.gz
docker start depsilo
curl -fsS http://127.0.0.1:23333/ready
printf '\nAfter checking Admin, policies and a client fetch, remove only this input volume:\ndocker volume rm %s\n' "$input_volume"
RESTORE

/ready 只检查就绪状态；还须核对管理员登录、策略、上游和真实客户端拉取。人工验证成功后，再执行脚本输出的 docker volume rm 命令，只删除本次临时输入卷。如果恢复、启动或验证失败，保留原始备份和 depsilo-state，不要清理输入卷，先排查并决定如何回滚。先在隔离环境演练整个流程；“归档已生成”不等于“恢复已经验证”。

Docker Desktop、rootless Docker、用户命名空间映射和特殊卷驱动的权限映射可能不同。如果辅助容器无法读取宿主归档或不能更改卷内所有权，准备阶段会中止；先在对应环境验证映射和卷权限，不要通过放宽归档到 0644 或以 root 执行实际恢复来绕过。

审计链检查点

[audit] checkpoint_file 会把审计链头检查点以 NDJSON 追加写入并 fsync， depsilo audit verify、完整性 API 和审计页都会逐条比对。检查点必须放在数据库所在的故障域之外：挂载到宿主机受控目录，或通过 [audit] checkpoint_url 推送到 WORM 网关 / 日志平台。两者都在数据库旁边时，“整库重写”依然无法发现。默认每 15 分钟写一次，可用 checkpoint_interval 调整。

上线前检查

固定 0.11.0 标签，要求更强可复现性时再固定镜像摘要。
通过 TLS 反向代理或受控网络暴露服务，限制 Admin 和首次设置入口。
持久化配置、SQLite 与本地缓存；对状态卷和备份实施最小权限。
把 JWT secret 等敏感值交给秘密管理系统，不写入镜像或版本库。
用 /ready 控制流量，用 doctor 排查完整链路，并定期执行恢复演练。