部署与配置

版本范围

本页只描述稳定版 v0.9.4 已发布的行为。生产环境请固定镜像标签或摘要，不要使用 latest；升级前应阅读目标版本的发布说明，并重新演练就绪检查和恢复流程。

推荐的 Docker 部署

下面的命令把配置、SQLite 数据库和本地对象缓存放进同一个命名卷：

终端

docker volume create depsilo-state

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

v0.9.4 的首次设置会把数据库和本地缓存的绝对路径写入生成的配置文件；新安装只需持久化 /root/.depsilo。官方镜像以固定 UID/GID 10001:10001 运行，新命名卷自动采用该所有权。 从旧 root 容器或 v0.9.0 Compose 布局升级时，先按带版本的升级指南处理旧状态。

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

如果把 storage.type 改为 s3，远端保存的只是对象缓存。配置和 SQLite 仍是本地状态， 仍须持久化和备份；S3 后端不会把 v0.9.4 变成多实例或高可用部署。

完成首次设置

docker logs depsilo

打开 http://localhost:23333，输入启动日志中的一次性 bootstrap token，然后创建首个 管理员。Depsilo 没有默认的 admin/admin 账号。不要把启动日志公开；创建管理员后也应 按组织的日志保留策略保护或清理其中的 bootstrap 信息。

配置来源与优先级

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

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

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

样例值不是默认值

config.example.toml 是一份会显式覆盖配置的完整样例，不是默认值清单。例如， v0.9.4 的内置 cache.ttl_index 是 5m，样例文件却写成 1h。复制样例后， 应逐项审阅，而不是假定省略和复制的效果相同。

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

配置项	v0.9.4 内置默认值	v0.9.4 样例文件	生产建议
server.host	0.0.0.0	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.9.4 会把数据库和缓存的实际默认路径迁到 ~/.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 缓存对象。它含有 用户、策略、审计和可能的秘密配置，应加密、限制访问并复制到故障域之外。缓存需要单独 保护，或接受恢复后从上游重新获取。

恢复前必须停止拥有目标数据库的服务。以下示例使用相同版本镜像，把当前目录中的归档 恢复到命名卷：

终端

docker stop depsilo

docker run --rm \
  -v depsilo-state:/root/.depsilo \
  -v "$PWD:/backup:ro" \
  -e DEPSILO_CONFIG=/root/.depsilo/config.toml \
  -e DEPSILO_DATABASE_DSN=/root/.depsilo/data/depsilo.db \
  -e DEPSILO_STORAGE_PATH=/root/.depsilo/data/cache \
  ghcr.io/depsilo/depsilo:0.9.4 \
  restore /backup/depsilo-backup.tar.gz

docker start depsilo
curl -fsS http://127.0.0.1:23333/ready

先在隔离环境演练恢复，并核对管理员登录、策略、上游和客户端拉取；“归档已生成”不等于 “恢复已经验证”。

上线前检查

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