# AutoLibrary Ubuntu 部署与迁移

日常发布可交给 [Gitea 自动部署](gitea-deployment.md)。本页用于首次迁移、数据备份与人工恢复。

## 部署组成

- Go 服务器：`webserver frontend`、`webserver backend`，或 `webserver start` 同时运行。
- 前端构建：Vue 应用的 `frontend/dist`，部署后无需 Node 服务。
- 运行数据：现有的三个 SQLite 数据库、主题文件目录、Casdoor 数据与配置。
- 入口：Nginx 继续反向代理 Go 前端；Go 将 `/api/*` 去掉 `/api` 前缀后代理到后端。

保留当前实际端口和域名。仓库内 Nginx 示例使用前端 3003、后端 8080，通用配置示例使用前端 3000。以部署机 `config.json` 为准。

## 1. 准备新版本

开发或构建机器需要 Go 1.25.6+ 和 Node.js 22.13+。推荐使用 Node 当前 LTS。

```sh
npm --prefix frontend ci
npm --prefix frontend run build
go test ./...
go build -o webserver .
```

SQLite 驱动使用 CGO；建议在 Ubuntu 上安装 `build-essential` 并在目标平台构建 Go 可执行文件，不要把 Windows 可执行文件直接部署到 Linux。

为每次发布准备单独目录，例如 `/opt/autolibrary/releases/20261016`。目录应包含：

```text
webserver
frontend/dist/
backend/templates/
config.json       # 部署机自己的配置，不用示例覆盖
```

保留 `frontend/dist` 中的完整资源目录，包括字体、截图与品牌图标。

## 2. 备份运行数据

停止旧 AutoLibrary 服务，保证 SQLite 备份与主题文件一致，再备份：

- 原部署程序和前端资源。
- `config.json`。
- `versions.db`、`bulletins.db`、`themes.db`，以及存在的 `-wal`、`-shm` 文件。
- 整个 `themes_files` 目录。
- Casdoor 数据库、证书和配置。

本次不重置数据库或 Casdoor。使用部署机既有账户；不要重新导入初始化数据覆盖账户。

## 3. 配置路径

推荐将持久数据放在 `/opt/autolibrary/shared/`，在 `config.json` 中使用绝对路径。例如：

```json
{
  "backend": {
    "host": "127.0.0.1",
    "port": "8080",
    "database": {
      "versions": { "path": "/opt/autolibrary/shared/versions.db" },
      "bulletins": { "path": "/opt/autolibrary/shared/bulletins.db" },
      "themes": { "path": "/opt/autolibrary/shared/themes.db" },
      "themes_files": { "path": "/opt/autolibrary/shared/themes_files" }
    }
  },
  "frontend": {
    "host": "127.0.0.1",
    "port": "3003",
    "static": { "path": "./frontend/dist" }
  }
}
```

以上仅展示需调整的字段；合并至实际完整配置，保留原 API Key、Casdoor client ID、secret 和证书。完整无密钥模板见根目录 `config.example.json`。

旧配置若仍指向 `frontend/public`，服务器在其同级找到 `dist/index.html` 时会使用新构建；仍建议显式改为 `frontend/dist`。

启动会为版本表添加 `gitea_*_url` 和 `release_notes_url` 列，不删除旧字段。历史 GitHub 下载地址不会被盲目改写。通过原版本管理 API 填入真实 Gitea 下载地址；未填写时，新官网引导访问 Gitea 发行页，云盘仍按原数据提供。

## 4. systemd

将 `/opt/autolibrary/current` 指向当前发布目录，并配置：

```ini
[Unit]
Description=AutoLibrary Website
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/autolibrary/current
ExecStart=/opt/autolibrary/current/webserver start --config /opt/autolibrary/shared/config.json
Restart=on-failure
RestartSec=5
TimeoutStopSec=20

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

Go 服务收到 SIGTERM 后先等待请求结束，再关闭数据库。Casdoor 继续使用原独立服务运行；若配置了服务依赖，沿用现有的 Casdoor unit 名称。

Nginx 通常无需更改。检查 `proxy_pass` 指向的端口与当前配置一致。`/changelog` 的永久跳转和页面路由由 Go 处理；不要增加将所有未知资源重写到首页的规则。

## 5. 上线验证

```sh
curl -I http://127.0.0.1:3003/
curl -I http://127.0.0.1:3003/marketplace/profile
curl -I http://127.0.0.1:3003/changelog
curl -i http://127.0.0.1:3003/not-a-real-page
curl http://127.0.0.1:3003/api/download/latest
curl http://127.0.0.1:8080/health
```

应分别得到页面成功、深层页面成功、301 跳转 `/downloads`、404、真实稳定版或空数据、健康状态。检查浏览器中的深浅主题、下载入口、市场筛选、登录、主题上传与管理员审核。

网站不再实时请求 GitHub 或 Gitea API 获取版本。发行说明与源码入口统一使用 Gitea；公告服务仍保留。

## 回滚

如需回滚，停止新服务，将 `current` 指回旧发布目录并恢复原配置，再启动旧程序。新增版本列属于增量改动，旧程序可忽略；若要恢复上线前的数据状态，应在停服后恢复同一批备份的数据库和主题文件。不要只回滚其中一部分。