plainleaf/deploy/nas/README.md

Plainleaf 极空间部署

Plainleaf 使用 Gitea Actions 自动发布。代码推送到 main 分支后会自动触发构建和 部署；也可以从 Gitea Actions 页面手动触发，用于发布失败后的重试。NAS 上的专用 Runner 在隔离 的 rootless Docker 中构建镜像，推送 edge 到 Gitea Registry，然后通过受限 SSH 密钥触发更新服务。不运行定时器，也不会轮询 Registry。 只有镜像 ID 变化时才会重建 plainleaf 容器，不会执行 compose down、Docker 清理或删除数据卷。

固定目录和端口：

• 部署目录：/data_s001/data/udata/real/13616066635/docker/plainleaf
• root 更新配置：/etc/plainleaf
• 服务配置：<部署目录>/data，容器内为 /data
• Markdown：/data_s001/data/udata/real/13616066635/笔记管理/Plainleaf，容器内为 /notes
• NAS 端口：31230
• 镜像：gitea.aichickenfarm.cn/wushenghua/plainleaf:edge

Markdown 目录始终是数据真源，发布和更新都不会移动、重命名或改写已有文档。

日常发布

启用 push 触发后，本机只需正常提交并推送代码：

git push

Gitea Actions 会构建 linux/amd64 镜像并同时推送两个标签：

• 当前 Git 短提交号，用于定位和人工回滚
• edge，供 NAS 自动更新

Mac 不需要安装 Runner，也不需要执行 docker login。Registry 令牌只保存在仓库 Actions Secret REGISTRY_TOKEN 中；NAS 部署私钥只保存在 NAS_DEPLOY_KEY 中。

NAS 首次启用

首次安装需要一次 SSH 和 sudo，之后日常发布不再上传镜像包，也不需要重复输入 SSH 或 sudo 密码。安装时要完成以下动作：

1. 将 compose.yaml 和现有 .env 复制到 root 持有的 /etc/plainleaf，配置 文件名为 /etc/plainleaf/plainleaf.env，并把 PLAINLEAF_IMAGE_TAG 设为 edge。更新服务只读取该目录，个人账号不能修改 root 更新流程。
2. 将 update-plainleaf.sh 安装为 /usr/local/sbin/plainleaf-update。
3. 将 systemd 单元安装到 /etc/systemd/system/plainleaf-update.service。
4. 生成专用的 ~/.ssh/plainleaf_zspace_ed25519，将公钥安装到 NAS。授权行使用 forced-command，并禁用端口转发、Agent 转发、PTY 和 X11；这把密钥只能触发 Plainleaf 更新，不能登录 Shell。发布脚本还会开启 BatchMode 和 IdentitiesOnly，不会回退到密码或其他密钥。
5. 安装 plainleaf-update.sudoers，其中只有一条受限规则，只允许 NAS 账号免密启动 plainleaf-update.service，不能免密执行其他 root 命令。
6. 执行 systemctl daemon-reload，再手动启动一次服务，确认拉取、重建和健康检查 成功。服务不会常驻，只有本机发布脚本主动调用时才运行。

仓库内的 install-update-service.sh 会执行上述 NAS 安装步骤。它会先用 visudo 校验规则，保留现有 .env 的路径和 UID/GID，只把镜像标签改成 edge；脚本本身 不会拉取镜像、启动服务或重建容器。

部署 .env 不存放账号密码，保留以下字段：

PLAINLEAF_IMAGE_TAG=edge
PLAINLEAF_UID=1001
PLAINLEAF_GID=1001
PLAINLEAF_PORT=31230
PLAINLEAF_SERVER_PATH=/data_s001/data/udata/real/13616066635/docker/plainleaf/data
PLAINLEAF_SPACE_PATH=/data_s001/data/udata/real/13616066635/笔记管理/Plainleaf

更新与回滚行为

plainleaf-update 每次只做以下事情：

1. 验证 Compose 中只有 plainleaf 服务，且镜像来自固定 Gitea 仓库。
2. 给当前容器镜像保留 rollback 标签。
3. 仅执行 docker compose pull plainleaf。
4. 镜像 ID 未变化时直接退出；变化时仅重建 plainleaf。
5. 等待容器健康；失败时重新标记旧镜像并恢复旧容器。

新镜像启动失败时不会删除，方便后续排查。更新日志可通过以下命令只读查看：

sudo systemctl status plainleaf-update.service
sudo journalctl -u plainleaf-update.service -n 100 --no-pager

账号模式初始化

空的 /data 会打开 https://<Plainleaf 域名>/.setup/。首个空间建议使用：

• 名称：Plainleaf
• URL 路径：/
• 数据目录：/notes

管理员可在 /.spaces/users 管理用户，在 /.spaces 分配空间访问权限。初始化和 更新都不会移动 Markdown；users.json、spaces.json 和会话密钥只写入 /data。

人工回滚

自动回滚失败时，可把 .env 的 PLAINLEAF_IMAGE_TAG 改为之前发布的 Git 短提交 号，再仅重建 plainleaf 服务。不要删除 /data、/notes、Docker volume， 也不要运行 docker system prune 或 docker compose down。