用 Docker Compose 部署

一台机器就能跑起完整的爬山虎：PostgreSQL、服务端和 BostonIvy Web，编排写在 bostonivy-os 仓库的 deploy/compose.yaml 里。这是最快的上手方式，家庭或小团队用它就够了。

开始之前

Docker 和 Compose v2（docker compose version 显示 v2.x）。
部署文件：bostonivy-os 的 deploy 目录，里面有 compose.yaml、https.yaml 和 .env.example。
镜像的读取权限。 镜像是 GitHub Container Registry 上的私有软件包。用带 read:packages 权限的 GitHub 令牌登录一次：

echo "$GITHUB_TOKEN" | docker login ghcr.io -u <你的 GitHub 用户名> --password-stdin

启动爬山虎

从示例生成配置：
```
cd deploy
cp .env.example .env
```
生成服务端密钥，填进 .env 的 BOSTONIVY_AUTH_SECRET：
```
docker compose run --rm --no-deps bostonivy keygen
```
启动全部服务：
```
docker compose up -d
```
打开 http://localhost:8080 注册账号。新库上第一个注册的账号自动成为管理员；之后是否允许别人注册，由 auth.open_registration 和管理面板里的设置决定。

docker compose ps 应该显示三个服务都是 healthy。服务端每次启动都会自动迁移数据库，不需要再运行别的命令。

示例 .env 里 BOSTONIVY_COOKIE_SECURE=false，只适合在 http://localhost 上试用。给别人用之前，请先配好 HTTPS（见下文），并把它改成 true。

配置

所有配置都在 deploy/.env 里：

变量	说明
`BOSTONIVY_AUTH_SECRET`	必填。所有签名和加密密钥都由它派生。丢失后所有人需要重新登录，加密保存的 TOTP 和 webhook 密钥也无法解开。请妥善备份
`BOSTONIVY_URL`	用户访问的地址，邮件里的链接和分享链接都用它
`BOSTONIVY_PORT`	本机暴露的端口，默认 `8080`
`BOSTONIVY_COOKIE_SECURE`	生产环境设为 `true`，这要求使用 HTTPS。只有在 `http://localhost` 上试用时设为 `false`，否则刷新页面后会掉登录
`BOSTONIVY_SMTP_URL`、`BOSTONIVY_MAIL_FROM`	发信设置，例如 `smtps://user:password@smtp.example.com` 和 `BostonIvy <noreply@example.com>`。留空表示不发邮件；`log` 表示把邮件写进服务端日志，适合试用
`POSTGRES_PASSWORD`	数据库密码
`BOSTONIVY_VERSION`	镜像标签；`latest` 跟随最新版本
`BOSTONIVY_SITE`	Caddy 的站点地址，见下文的 HTTPS 一节

其他服务端配置（限流、Redis、webhook、对象存储、注销账号的宽限期等）都可以用 BOSTONIVY_<段>__<键> 形式的环境变量设置，例如 BOSTONIVY_STORAGE__KIND=s3，加在 compose.yaml 的 bostonivy.environment 里即可。完整的配置项见 bostonivy-os 里的 bostonivy.example.toml。

HTTPS

二选一：

让 Caddy 申请证书。 把域名解析到这台机器，然后在 .env 里设置：
```
BOSTONIVY_SITE=tasks.example.com
BOSTONIVY_URL=https://tasks.example.com
BOSTONIVY_COOKIE_SECURE=true
```
再加上 HTTPS 的覆盖文件启动，它会打开 80 和 443 端口：
```
docker compose -f compose.yaml -f https.yaml up -d
```
Caddy 会自动申请和续期证书，证书保存在 caddy 卷里。
放在已有的反向代理后面。 保持 BOSTONIVY_SITE=:80，把代理指向 BOSTONIVY_PORT，并确认它转发 /api/v1/realtime 上的 WebSocket 连接，实时更新靠它推送。

备份与升级

需要备份三样东西：

数据库：

docker compose exec postgres pg_dump -U bostonivy bostonivy > backup.sql

附件和头像： files 卷（如果已改用 S3，就在存储桶里）。
密钥： .env 里的 BOSTONIVY_AUTH_SECRET。

升级时拉取新镜像并重启：

docker compose pull && docker compose up -d

新版本启动时会自动迁移数据库。迁移只增不删，配合备份可以回退到上一个版本。

命令行

docker compose exec bostonivy bostonivy admin promote <用户名>   # 设为管理员
echo "新密码" | docker compose exec -T bostonivy bostonivy admin set-password <用户名>
docker compose exec bostonivy bostonivy health                  # 健康检查

自己构建镜像

把 bostonivy-web 检出到 bostonivy-os 旁边，或者在 .env 里用 BOSTONIVY_WEB_SOURCE 指定路径。网页版依赖私有的爬山虎设计包，所以构建时需要一个能读取 IvyLabsApp 私有仓库的令牌。令牌只作为构建密钥使用，不会写进镜像：

cd deploy
GITHUB_TOKEN=$(gh auth token) docker compose build
docker compose up -d