Docker Compose 部署

准备

先确认 docker version 和 docker compose version 能正常返回。以下是 Docker Compose v2 命令

新建一个专用目录，例如 Linux /opt/password-xl-stack 或 Windows D:\password-xl-stack。在其中创建 compose.yaml 和 data 子目录。不要放进临时下载目录

配置文件

services:
  password-xl:
    image: ccr.ccs.tencentyun.com/password-xl/password-xl-service:latest
    container_name: password-xl-service
    restart: unless-stopped
    ports:
      - '9080:8080'
    volumes:
      - ./data:/password-xl-service

./data 相对于 Compose 文件所在目录。将来移动整个目录时，应把 compose.yaml 和 data 一起移动，并在启动前检查解析后的绝对路径

启动并检查

下面命令在 Bash、PowerShell 和 CMD 中相同，请先进入保存配置文件的目录：

docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail 100

config 应能正常输出展开后的配置。服务日志出现启动成功后，访问 http://服务器IP:9080

首次使用

从 data/password-xl.toml 或首次日志取得随机初始登录密码。按 Docker 首次登录步骤修改配置，然后运行：

docker compose restart

查看原尺寸

首次连接私有服务，使用自己的服务地址和 TOML 账号

创建主密码，保存测试记录，再 docker compose restart 并重新解锁，确认数据仍在

升级与备份

1. 导出 JSON 密码备份
2. 停止服务：docker compose stop
3. 复制整个 data 目录到独立备份位置，并保存当前镜像摘要
4. 运行 docker compose pull、docker compose up -d
5. 检查日志、登录、记录数量与抽样内容

docker compose down 会移除服务容器；本例绑定的宿主机 data 目录仍需自行管理。不要把删除目录当作升级步骤。回退应恢复升级前目录并使用原镜像摘要，见升级与回退

故障处理

配置缩进错误时先运行 docker compose config，不要盲目反复启动。端口冲突时改冒号左侧的 9080。换目录后出现空库时，停止服务，核对 volumes 解析路径是否仍是原数据目录