Docker 整合部署（推荐）
一个容器同时提供页面和存储，完整讲解挂载、初始密码与首次保存
本教程使用 README 关联 NAS 教程中的后端整合镜像：
ccr.ccs.tencentyun.com/password-xl/password-xl-service:latest它包含前端页面，无需再安装前端或数据库。示例把宿主机 9080 端口映射到容器 8080，将宿主机数据目录挂载到容器 /password-xl-service
1. 准备环境
准备已安装 Docker Engine 或 Docker Desktop 的设备，以及可写的持久化目录。Windows 的 Docker Desktop 应使用 Linux 容器模式
docker version
docker infodocker version 应同时显示 Client 和 Server。只有 Client、提示无法连接 Docker daemon 时，先启动 Docker 服务
检查 9080 未被其他应用占用。需要从其他设备访问时，防火墙只放行必要的内网来源；公网访问另行配置 HTTPS
2. 拉取并启动
选择与你使用的终端对应的一组命令。不要把 Bash 的反斜杠换行直接复制进 PowerShell 或 CMD。 Windows 示例使用一行命令，避免续行符歧义
Linux / NAS SSH（Bash）
sudo mkdir -p /opt/password-xl
docker pull ccr.ccs.tencentyun.com/password-xl/password-xl-service:latest
docker run -d \
--name password-xl-service \
--restart unless-stopped \
-p 9080:8080 \
--mount type=bind,source=/opt/password-xl,target=/password-xl-service \
ccr.ccs.tencentyun.com/password-xl/password-xl-service:latest使用非 root 运行 Docker 时，请确保运行账号有权操作 Docker 和宿主机数据目录。不要通过把目录设为所有人可写来长期解决权限问题
Windows PowerShell
New-Item -ItemType Directory -Force -Path 'D:\password-xl-data'
docker pull ccr.ccs.tencentyun.com/password-xl/password-xl-service:latest
docker run -d --name password-xl-service --restart unless-stopped -p 9080:8080 --mount "type=bind,source=D:\password-xl-data,target=/password-xl-service" ccr.ccs.tencentyun.com/password-xl/password-xl-service:latestWindows CMD
mkdir D:\password-xl-data
docker pull ccr.ccs.tencentyun.com/password-xl/password-xl-service:latest
docker run -d --name password-xl-service --restart unless-stopped -p 9080:8080 --mount "type=bind,source=D:\password-xl-data,target=/password-xl-service" ccr.ccs.tencentyun.com/password-xl/password-xl-service:latest第一次运行后输出一串容器 ID。接着检查：
docker ps --filter name=password-xl-service
docker logs --tail 100 password-xl-service成功标志是容器持续处于运行状态，日志出现“服务启动成功”，端口映射显示 9080->8080
3. 取得初始登录密码
数据目录中没有可用配置文件时，程序会生成 password-xl.toml。默认用户名是 password-xl，登录密码为本次启动生成的 16 位随机字母数字组合，可从首次启动日志或宿主机配置文件中查看
这不是统一默认密码，不要照抄他人日志中的密码。重新启动已有数据目录不会主动生成新的账号配置
配置文件位于：
| 环境 | 宿主机上的配置文件 |
|---|---|
| 本教程 Linux 示例 | /opt/password-xl/password-xl.toml |
| 本教程 Windows 示例 | D:\password-xl-data\password-xl.toml |
| 容器内路径 | /password-xl-service/password-xl.toml |
4. 修改服务登录密码并重启
在宿主机上编辑生成的 password-xl.toml，保留用户名，把 password 改为自己的强密码。这里的文本仅说明文件结构，不要原样使用示例密码
[[user]]
username = "password-xl"
password = "替换为你独立生成的强密码"保存为 UTF-8 文本，保留双引号，不要使用中文弯引号。服务只在启动时加载用户配置，因此修改后执行：
docker restart password-xl-service
docker logs --tail 50 password-xl-service日志仍应显示服务启动成功。编辑配置改变的是服务登录密码，不会改变已有密码库的主密码
5. 打开页面并首次保存
- 同一台电脑访问
http://localhost:9080；其他内网设备访问http://服务器IP:9080 - 在页面选择“私有服务”。服务地址填写页面所连接的地址，例如
http://192.168.1.20:9080 - 填入自己的用户名和刚修改的服务登录密码
- 空密码库按提示设置主密码，妥善保存
- 添加一条测试记录，等待保存成功提示，重新打开确认记录存在
手机访问 NAS 时不要填写 localhost：手机的 localhost 指向手机自身，应该填写 NAS 的内网地址
6. 验证持久化
docker inspect password-xl-service --format '{{json .Mounts}}'
docker restart password-xl-service检查 Mounts 中 Destination 为 /password-xl-service，Source 为你准备的宿主机目录。重启后重新登录解锁，测试记录应仍然存在
主要目录结构：
password-xl-data/ ← 宿主机选定的持久化目录
├── password-xl.toml ← 服务账号配置
└── password-xl-data/
└── password-xl/ ← 用户名对应的目录
├── store.json ← 加密的密码和标签数据
└── setting.json ← 设置数据这里外层目录名称可以自行选择；内层 password-xl-data 是服务使用的结构。不要因名称相似而少备份一层
CPU 不兼容时使用 JVM 镜像
若原生镜像启动时报 CPU 指令集不兼容、Illegal instruction 等错误，可以核对并尝试项目的 JVM 镜像：
ccr.ccs.tencentyun.com/password-xl/password-xl-service-jvm:latest先停止原容器并备份挂载目录，用新容器名称、同一端口和同一持久化目录启动 JVM 镜像。不要让两个容器同时写入同一目录
镜像格式和 CPU 架构是两件事。安装前可以检查真实镜像清单：
docker buildx imagetools inspect ccr.ccs.tencentyun.com/password-xl/password-xl-service:latest
docker buildx imagetools inspect ccr.ccs.tencentyun.com/password-xl/password-xl-service-jvm:latest只有清单列出的平台才是该标签实际提供的架构，不根据“支持 Docker”推断支持所有 NAS CPU
2026-09-07 实际查询结果：上述原生镜像和 JVM 镜像的 latest 均提供 linux/amd64。ARM NAS 不能把 JVM 版本直接当作 arm64 镜像使用；未来标签可能更新，安装时请再次核对清单
常见问题与下一步
| 问题 | 检查 |
|---|---|
| 端口被占用 | 只改宿主机端口，例如 9081:8080，访问地址随之调整 |
| 浏览器打不开 | 容器状态、日志、服务器 IP、防火墙、实际端口映射 |
| 登录失败 | 服务地址和 TOML 账号；修改配置后是否重启 |
| 重启后提示重新设置主密码 | Mounts 是否指向原目录、用户名是否变了；先停止写入并找回原目录 |
| HTTPS 页面无法连接 HTTP 服务 | 使用服务自带页面或配置 HTTPS |
| 权限错误 | 挂载目录是否存在且可写，容器日志中的真实错误 |