# 通过 Gitea Actions 部署官网

推送到网站仓库的 `main` 后，Gitea 把任务交给 Ubuntu 部署机上的专用 Runner。Runner 检出该次提交，使用锁文件安装前端依赖，执行前端构建、`go test ./...` 和启用 CGO 的 Go 编译。每次发布生成独立目录，原子切换 `current`，重启 systemd 服务并检查首页和 `/api/health`。检查失败时自动切回上一发布，并将本次任务标记为失败。

## 1. 准备 Ubuntu 部署机

安装 Bash、Git、curl、sudo、`build-essential`、`util-linux`、Go 1.25.6 或更新版本、Node.js 22.13 或更新版本。确认 Runner 的服务环境中能找到 `git`、`node`、`npm`、`go` 和 `gcc`，并能访问 Gitea、GitHub 上固定版本的 checkout Action、npm registry 和 Go 模块代理。

部署使用两个专用账号。首次创建账号及目录时运行以下命令。已有同名账号时复用，并确认组和权限与示例相符。

```sh
sudo useradd --system --user-group --create-home --home-dir /var/lib/autolibrary-runner autolibrary-deploy
sudo useradd --system --user-group --no-create-home autolibrary
sudo chmod 0700 /var/lib/autolibrary-runner
sudo install -d -o root -g autolibrary-deploy -m 1775 /opt/autolibrary
sudo install -d -o autolibrary-deploy -g autolibrary-deploy -m 0755 /opt/autolibrary/releases
sudo install -d -o root -g autolibrary -m 0771 /opt/autolibrary/shared
sudo install -d -o autolibrary -g autolibrary -m 0750 /opt/autolibrary/shared/logs
```

从现有站点迁移时，按 [Ubuntu 部署说明](migration-to-ubuntu.md) 停服备份，再迁入现有配置和数据。新站点可以从 `config.example.json` 起步并填入实际参数。生产配置路径为 `/opt/autolibrary/shared/config.json`，文件权限设为 `0640`，所有者设为 `root:autolibrary`。配置应包括：

- SQLite 数据库和主题文件使用发布目录之外的绝对路径，例如 `/opt/autolibrary/shared/themes.db` 与 `/opt/autolibrary/shared/themes_files`。运行用户 `autolibrary` 需要对数据库所在目录和主题文件目录有写权限。
- `frontend.host` 监听 `127.0.0.1`，`frontend.static.path` 使用 `./frontend/dist`。生产端口与现有 Nginx upstream 对齐。
- 保留生产 API Key、Casdoor 配置及独立运行的 Casdoor 服务。启用 API Key 校验时填写实际的 Key。

已有 `current` 时，它应为指向上一版的符号链接。核实上一版可用新 unit 和共享配置启动，并把该链接本身交给部署账号（`sudo chown -h autolibrary-deploy:autolibrary-deploy /opt/autolibrary/current`），以便部署替换和回滚。若原站使用其他 unit，在第一次自动发布前停止并禁用该旧 unit，避免争用端口。

## 2. 安装网站服务和 Runner

从网站源码目录安装 unit。它在首次发布时启动。

```sh
sudo install -m 0644 deploy/autolibrary-webserver.service /etc/systemd/system/autolibrary-webserver.service
sudo systemctl daemon-reload
sudo systemctl enable autolibrary-webserver.service
sudo visudo -f /etc/sudoers.d/autolibrary-deploy
```

加入以下精确授权，使 Runner 可以操作网站 unit。

```sudoers
autolibrary-deploy ALL=(root) NOPASSWD: /usr/bin/systemctl restart autolibrary-webserver.service, /usr/bin/systemctl stop autolibrary-webserver.service
```

在 Gitea 创建一个空的网站源码仓库，启用仓库的 Actions 功能并保护 `main`。使用该网站仓库的 Runner 注册令牌，在部署机安装 [Gitea Runner](https://docs.gitea.com/runner/)，然后以部署账号交互注册：

```sh
sudo -u autolibrary-deploy -H sh -c 'cd "$HOME" && gitea-runner register'
```

输入实例地址和仓库级令牌，标签只填写 `autolibrary-production:host`。以同一账号和工作目录运行 `gitea-runner daemon`。可用下面的 systemd unit 持久运行，将 `ExecStart` 与 `PATH` 调整到实际安装位置。

```ini
[Unit]
Description=AutoLibrary Gitea Runner
Wants=network-online.target
After=network-online.target

[Service]
User=autolibrary-deploy
WorkingDirectory=/var/lib/autolibrary-runner
Environment=PATH=/usr/local/go/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/usr/local/bin/gitea-runner daemon
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

例如保存为 `/etc/systemd/system/autolibrary-runner.service` 后，执行 `sudo systemctl daemon-reload` 和 `sudo systemctl enable --now autolibrary-runner.service`。旧版 Runner 的二进制名可能为 `act_runner`，按实际名称替换。确认仓库设置页中 Runner 在线，并且标签与工作流的 `runs-on` 一致。宿主机任务使用部署账号的权限直接运行，只将这个 Runner 分配给受信任的网站仓库。

## 3. 首次推送

在 Gitea 仓库的 Actions Variables 中将 `AUTOLIBRARY_PORT` 设为生产 `frontend.port`；省略时为 `3003`，若沿用通用示例配置则设置为 `3000`。

在本地网站源码目录绑定新建仓库的克隆地址并推送：

```sh
git remote add origin <Gitea 网站源码仓库的克隆地址>
git push -u origin main
```

在 Gitea 的 Actions 页确认部署任务完成。之后日常发布只需推送 `main`。发布脚本在切换前读取远端 `main`，已过时的任务会跳过部署。生产密钥、数据库、上传目录和 Casdoor 实例数据由部署机保存。

## 排查和回滚

- 任务排队时，检查仓库 Actions 设置、Runner 在线状态和标签。
- 重启或健康检查失败时，检查 Actions 日志和 `sudo journalctl -u autolibrary-webserver.service -n 100`。检查端口、共享配置、数据路径和权限。
- 发生业务回归时，用 `git revert` 后推送 `main` 重新构建上一份可用代码。紧急切回已有目录时，先确保 Runner 没有在部署，再按 [Ubuntu 部署说明](migration-to-ubuntu.md#回滚) 切换 `current`。清理历史发布目录前确认其未被 `current` 使用，并至少保留一个可用的上一版。
- 自动回滚切换的是程序和静态文件。涉及数据库结构变化时，上线前备份共享数据，并确认旧版本兼容变更后的结构。