Initialize AutoLibrary website with Gitea deployment

docs/migration-to-ubuntu.md

@@ -0,0 +1,122 @@
+# 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` 指回旧发布目录并恢复原配置，再启动旧程序。新增版本列属于增量改动，旧程序可忽略；若要恢复上线前的数据状态，应在停服后恢复同一批备份的数据库和主题文件。不要只回滚其中一部分。