0033 系统服务命令、Helm Chart 与部署冒烟测试
- 状态:已接受(2026-10-31)
- 相关:设计文档 02 F76;04 §9、§13(M4 验收);ADR 0009、0013、0029
背景
M4 最后一部分(ADR 0029):Helm、skinloom service install,以及"四种部署形态按文档从零部署成功"这条验收。
- 后台常驻靠发行包
service/目录里手写的三份文件:systemd 单元、launchd plist、Windows 任务计划脚本。Windows 上其实是计划任务而不是服务;三份文件各自要改路径,和程序里的逻辑也是两份。 - Kubernetes 只有 Kustomize 清单,改参数要改文件。
- 部署文件在 CI 里只做了语法检查(
compose config、kubeconform),从来没有真正启动过。本机不运行 Docker(ADR 0013 时的约定)。
决策
skinloom service install | uninstall | start | stop | restart | status,用 kardianos/service v1.3.0(MIT),一套代码覆盖三种系统:- Linux:systemd 单元由程序生成,沿用原单元的全部沙箱选项(
ProtectSystem=strict,只能写data/与前端缓存)。默认以skinloom用户运行(--user可改),这个用户要先建好;安装时把数据目录交给它。 - macOS:
/Library/LaunchDaemons下的系统守护进程,开机运行、退出后重启。 - Windows:真正的 Windows 服务,以 LOCAL SERVICE 运行,延迟自动启动,失败后 5 秒重启。安装时用 icacls 只给它
data\与前端缓存的写权限。 - 服务运行的是
skinloom service run --data <目录>,与skinloom up相同,另外响应服务管理器的启动与停止。站点自己退出时(比如配置错误)进程也退出,让服务管理器重启,而不是看起来在运行、实际什么都不服务。 - 安装先注册服务、再改权限;改权限失败就把服务删掉。没有管理员权限时直接失败,并提示用管理员终端或 sudo。
- 发行包的
service/目录和deploy/service/下的三份文件删除。
- Linux:systemd 单元由程序生成,沿用原单元的全部沙箱选项(
- 日志文件
log.file(冷键,相对于数据目录):配置了就同时写文件;以服务运行且没有配置时,写logs/skinloom.log,因为服务的控制台没人看,一次性安装链接会丢。启动时文件超过 20 MB,就保留一份为.1。先写文件再写控制台:Windows 服务的标准错误可能是无效句柄,io.MultiWriter遇到第一个错误就会停。 /readyz等前端就绪:web.mode为 managed 或 dev(前端是本进程的子进程)时,/readyz还要能连上前端端口。否则启动后有一秒左右,就绪探针已经通过,页面却返回 502。external(前后端分离)时前端有自己的探针,后端不依赖它。- Helm Chart
deploy/helm/skinloom:mode: allInOne(默认,单 Pod、SQLite、5 Gi 卷)或split(后端加前端,前端带 PDB,可选 HPA)。- 数据库:
database.driver,PostgreSQL / MySQL 的 DSN 从已有的 Secret 读取,不进 values。 - 其余:
ingress.*、persistence.*(卸载 Chart 时保留数据卷)、trustedProxies、server.extraEnv(例如 S3)、资源、调度。安全设置与 Kustomize 清单一致:非 root、去掉全部 capabilities、seccomp、不挂载 ServiceAccount 令牌。 - 互相矛盾的参数在渲染时报错并说明原因:SQLite 配多个后端副本;多副本却用 ReadWriteOnce 卷;allInOne 配多副本;外部数据库没给 Secret。
- Kustomize 清单保留,给不想装 Helm 的人用。
- 不做迁移 Job:后端启动时带锁执行迁移(ADR 0003)。没有指标接口,所以也不做 ServiceMonitor。
- 部署冒烟测试:
deploy/smoke/smoke.sh像新站长一样使用站点,依次检查:等待就绪、首页能渲染、从日志里取安装链接完成安装、登录、创建角色、用 CustomSkinLoader 接口取回角色、系统状态没有 error。- 新工作流
deploy-smoke.yml在 GitHub 的机器上对每种部署方式跑一遍:- Compose 的三个变体(minimal、standard、postgres);
- Helm 在 kind 集群上(allInOne + SQLite,split + PostgreSQL);
- Linux 发行包:先按文档前台启动,再用
skinloom service install注册为 systemd 服务。
- 镜像都从当前提交构建,不拉取已发布的镜像。
- 原有的
Deployment files任务加上 Helm 的 lint、多组参数渲染、kubeconform 校验和非法参数的拒绝检查。
- 新工作流
- Windows 发行包的 zip 改用 Windows 10 以上自带的
tar.exe(没有zip时)。Windows PowerShell 的Compress-Archive把\写成路径分隔符,unzip会警告,macOS 与部分工具会解压错。
影响
- 新依赖
github.com/kardianos/service;新命令service;新配置log.file。 - 发行包不再有
service/目录,文档与 README 改为skinloom service install。 - Docker、Compose、Helm 的从零部署由 CI 的冒烟测试验证,本机只验证发行包。