79 lines
5.6 KiB
Markdown
79 lines
5.6 KiB
Markdown
# Release、安装与更新
|
||
|
||
TallyNote 的发布包必须在目标 Linux 架构上构建。`better-sqlite3`、`argon2`、`sharp` 和 Node runtime 都包含原生代码，不能在 macOS 上交叉打包后冒充 Linux。
|
||
|
||
正式支持：Linux x86_64/amd64；脚本和安装器也支持在原生 runner 上提供 Linux aarch64/arm64（glibc 或 musl）。当前仓库 workflow 只生成 x64，arm64 必须使用对应 runner 单独构建发布。ARMv7/ARM32 只在你拥有对应 runner 和完整依赖构建结果时实验使用。Linux x86 32 位（i386、i686、ia32）明确不支持，Node.js 24 及原生依赖没有可维护的正式构建，因此安装器会拒绝它。
|
||
|
||
## 自动发布
|
||
|
||
向 Gitea 推送符合 SemVer 的 tag（例如 `v1.1.0`）会触发 `.gitea/workflows/release.yml`：
|
||
|
||
1. 在 Linux runner 上安装依赖，执行 `pnpm check`、`pnpm test` 和 `pnpm release:build`。
|
||
2. 由 `scripts/publish-gitea-release.sh` 计算所有归档的 `SHA256SUMS`。
|
||
3. 用 Ed25519 私钥生成 `SHA256SUMS.sig`，通过 Gitea Releases API 创建/复用对应 Release，并幂等上传归档、清单和签名。
|
||
|
||
在仓库的 Actions secrets 配置：
|
||
|
||
- `GITEA_TOKEN`：仅授予当前仓库 Release 写权限的 token。
|
||
- `TALLYNOTE_RELEASE_SIGNING_KEY`：Ed25519 私钥 PEM。它只作为 CI secret 使用，绝不能提交到 Git。
|
||
|
||
也可以在 Linux 发布机上手动执行：
|
||
|
||
```bash
|
||
pnpm install --frozen-lockfile
|
||
pnpm check && pnpm test
|
||
pnpm release:build 1.1.0 ./release
|
||
GITHUB_REPOSITORY=awaioi/TallyNote \
|
||
GITEA_TOKEN=... \
|
||
TALLYNOTE_RELEASE_SIGNING_KEY_FILE=/root/secrets/tallynote-release.key \
|
||
./scripts/publish-gitea-release.sh v1.1.0 ./release
|
||
```
|
||
|
||
发布资产名称必须包含当前平台，例如 `tallynote-1.1.0-linux-x64-glibc.tar.gz`。同一个 Release 只保留一个 `SHA256SUMS` 和一个 `SHA256SUMS.sig`，清单签名覆盖其完整原文。
|
||
|
||
## curl 安装
|
||
|
||
安装器默认只做 dry-run；只有显式 `--apply` 才会下载或写盘。正式安装必须同时提供 Ed25519 公钥和 `SHA256SUMS.sig`，公钥应通过独立的受信渠道核对指纹。下面示例假设公钥已安全放在服务器 `/root/tallynote-update.pub`：
|
||
|
||
```bash
|
||
curl --proto '=https' --tlsv1.2 -fsSL \
|
||
https://git.awaioi.com/awaioi/TallyNote/raw/branch/main/install.sh \
|
||
| sudo bash -s -- --apply --version 1.1.0 \
|
||
--signing-key /root/tallynote-update.pub \
|
||
--update-public-key-file /root/tallynote-update.pub
|
||
```
|
||
|
||
脚本会从 `https://git.awaioi.com/awaioi/TallyNote/releases/download/v<版本>/` 下载当前架构归档、`SHA256SUMS` 和 `SHA256SUMS.sig`，限制 HTTPS 重定向只能落在配置的受信主机，校验压缩/展开大小、条目数量、路径和特殊文件，再原子切换 `/opt/tallynote/current`。自定义仓库时同时设置 `TALLYNOTE_REPOSITORY_URL`、`TALLYNOTE_RELEASE_API_URL` 和 `TALLYNOTE_RELEASE_ALLOWED_HOSTS`；若使用独立 CDN，必须把 CDN 主机显式加入白名单。
|
||
|
||
已有安装默认拒绝安装不高于当前版本的 release；只有在明确执行 `--allow-downgrade`（或设置 `TALLYNOTE_ALLOW_DOWNGRADE=true`）时才允许回退版本。
|
||
|
||
`--allow-unsigned` 只用于隔离的开发/测试主机，不能用于公网或保存真实财务数据的服务器。安装器拒绝预先存在的符号链接、非 root 拥有或对组/其他用户可写的安装、配置和备份目录。
|
||
|
||
安装布局：
|
||
|
||
```text
|
||
/opt/tallynote/releases/<version>/ # 只读发布代码
|
||
/opt/tallynote/current -> releases/<version>
|
||
/opt/tallynote/.update-work/ # 0700 root:root，root 更新器临时工作区
|
||
/opt/tallynote/.update-state # root 更新状态标记，异常中断后用于恢复
|
||
/var/lib/tallynote/ # SQLite、附件、暂存和导出
|
||
/var/lib/tallynote-backups/ # 更新前数据备份
|
||
/etc/tallynote/tallynote.env
|
||
```
|
||
|
||
## 后台一键更新
|
||
|
||
将环境文件中的 `TALLYNOTE_UPDATE_STRATEGY=systemd`、`TALLYNOTE_UPDATE_METADATA_URL`、`TALLYNOTE_UPDATE_ALLOWED_HOSTS` 和 `TALLYNOTE_UPDATE_PUBLIC_KEY_FILE` 配好后，后台“系统更新”会读取 Gitea 的 `/api/v1/repos/<owner>/<repo>/releases/latest`。检查结果只显示当前平台匹配且同时通过 SHA-256 与 Ed25519 签名验证的资产；缺少任一项时“更新”按钮保持禁用。
|
||
|
||
浏览器只能提交版本号和确认标志。Web 进程把受保护的任务文件交给 root 的 `tallynote-update.path`/`tallynote-update.service`，root runner 会重新读取配置源、重新下载并验证 metadata、清单和签名，不信任队列文件中的 URL 或摘要。更新前会备份数据，切换失败或健康检查失败会恢复旧版本；手动回滚：
|
||
|
||
```bash
|
||
sudo /usr/local/sbin/tallynote-update --rollback
|
||
```
|
||
|
||
更新检查和应用接口带有冷却时间（可用 `TALLYNOTE_UPDATE_CHECK_COOLDOWN_SECONDS`、`TALLYNOTE_UPDATE_APPLY_COOLDOWN_SECONDS` 调整），避免反复触发外部请求。服务单元默认仅监听 `127.0.0.1`，并使用最小化 systemd 权限；公网访问必须通过 HTTPS 反向代理，设置真实 `TALLYNOTE_PUBLIC_ORIGIN`、`TALLYNOTE_COOKIE_SECURE=true` 和明确的 `TALLYNOTE_TRUST_PROXY` 跳数。
|
||
|
||
更新任务详情按发起管理员隔离，任务错误只返回固定提示，不会把服务器路径、命令输出或上游响应泄露到浏览器；同一时刻仍只允许一个系统更新任务。
|
||
|
||
业务导出不是备份。停服后复制完整 `/var/lib/tallynote` 数据目录（含数据库、WAL/SHM、附件、暂存、导出和更新任务文件），并限制 SSH、备份和磁盘权限。拥有服务器文件权限的人仍可直接读取底层财务数据。
|