98 lines
5.2 KiB
Markdown
98 lines
5.2 KiB
Markdown
# AutoLibrary Website
|
||
|
||
北京建筑大学图书馆自动化工具的官网、软件下载中心与社区主题市场。
|
||
|
||
- 产品仓库：<https://gitea.kenanzhu.com/KenanZhu/AutoLibrary>
|
||
- 用户手册：<https://manuals.autolibrary.kenanzhu.com>
|
||
- 发行版本：<https://gitea.kenanzhu.com/KenanZhu/AutoLibrary/releases>
|
||
|
||
## 架构
|
||
|
||
前端采用 Vue 3、TypeScript、Vite、Vue Router、Pinia 和 Lucide 图标。所有字体、图标和图片随构建产物提供，无需第三方 CDN。页面使用统一的布局、表单和状态组件，深浅主题由 CSS 语义变量管理。
|
||
|
||
Go/Gin 前端服务提供构建产物并将 `/api/*` 代理到后端；后端保留 GORM/SQLite、Casdoor 和本地主题文件存储。既可一起启动，也可分别部署。当前面向单实例运行。
|
||
|
||
```text
|
||
frontend/
|
||
src/
|
||
api/ # 请求、响应、下载和错误处理
|
||
components/ # 全站与业务共享组件
|
||
composables/ # 画廊等可复用交互逻辑
|
||
pages/ # 按路由拆分的页面
|
||
stores/ # 账户与外观状态
|
||
styles/ # 页面专用样式
|
||
site.ts # 项目链接、URL 和日期工具
|
||
types.ts # API 数据类型
|
||
styles.css # 双主题变量与响应式样式
|
||
public/assets/ # 原有品牌标识与实机截图
|
||
dist/ # 生产构建产物（生成）
|
||
backend/
|
||
handlers/themes_handler/ # 认证、查询、上传、更新、审核、下载
|
||
services/ # 主题打包、文件存储、事务协调、用户缓存
|
||
database/ # SQLite 初始化
|
||
models/ # 数据模型
|
||
```
|
||
|
||
## 本地开发
|
||
|
||
需要 Go 1.25.6+ 和 Node.js 22.13+（推荐当前 Node LTS，Vite 要求 Node 22.12+，ESLint 要求 22.13+）。从项目根目录运行：
|
||
|
||
```sh
|
||
# 首次配置；已有 config.json 时保留原文件
|
||
cp config.example.json config.json
|
||
npm --prefix frontend ci
|
||
go run . backend
|
||
```
|
||
|
||
在另一个终端启动前端：
|
||
|
||
```sh
|
||
npm --prefix frontend run dev
|
||
```
|
||
|
||
开发地址为 `http://127.0.0.1:5173`。默认代理到 `http://127.0.0.1:8080`；后端端口不同时，在 `frontend/.env.local` 设置 `API_PROXY_TARGET=http://127.0.0.1:实际端口`。无需在前端添加服务器密钥。
|
||
|
||
登录与注册需要配置并启动 Casdoor。未配置时，浏览下载和主题市场仍可用；账户操作会显示服务未启用。管理员审核统一使用 Casdoor 管理员账户。
|
||
|
||
## 构建与检查
|
||
|
||
```sh
|
||
npm --prefix frontend run typecheck
|
||
npm --prefix frontend run check
|
||
npm --prefix frontend run build
|
||
go test ./...
|
||
go build -o webserver .
|
||
./webserver start
|
||
```
|
||
|
||
`build` 已包含类型、ESLint 和 Prettier 检查，产物位于 `frontend/dist`。使用 `npm --prefix frontend run format` 统一前端源码格式。没有增加测试用例或测试工具链。Go 检查用于验证已有包可以编译。
|
||
|
||
生产环境默认访问 `http://127.0.0.1:3000`，实际地址以 `config.json` 为准。`frontend` 和 `backend` 子命令支持独立启动，均可使用 `--config /absolute/path/config.json`。请将工作目录设置为项目部署目录。
|
||
|
||
## 发行与下载数据
|
||
|
||
版本数据库是官网版本信息的唯一来源。首页通过 `GET /api/download/latest` 获取最新已发布的稳定版（按 `releaseDate`、ID 降序；无稳定版时 `data: null`），下载列表保持原有分页接口。`/api` 前缀由 Go 前端或 Vite 代理移除，直接访问后端时使用 `/download/latest` 等路径。
|
||
|
||
版本模型新增以下字段，启动时由 GORM 增量添加列，不删除原字段或数据：
|
||
|
||
| JSON 字段 | 用途 |
|
||
| --- | --- |
|
||
| `giteaZipUrl` | Gitea Windows 便携包 |
|
||
| `giteaInstallerUrl` | Gitea Windows 安装程序 |
|
||
| `giteaDmgUrl` | Gitea macOS 安装包 |
|
||
| `releaseNotesUrl` | 对应版本的发行说明 |
|
||
|
||
使用已有受 API Key 保护的 `POST/PUT /download/versions` 接口维护这些字段。提供真实的 Gitea 附件地址；不要仅将历史 GitHub URL 替换域名。新页面没有可用附件地址时，提供 Gitea 发行列表入口，云盘下载照常保留。原 `github*Url` 字段继续供已有 API 调用使用，新页面不再展示 GitHub 下载入口。
|
||
|
||
独立更新日志已移除，`/changelog` 永久跳转 `/downloads`。发行说明在 Gitea 查看；公告接口及其数据库保留。个人下载历史尚未实现，本次没有扩展该功能。
|
||
|
||
## 发布与维护
|
||
|
||
网站源码推送到 Gitea 的 `main` 后，由专用 Runner 构建、验证并发布网站镜像到 Gitea。镜像运行、数据挂载和切换步骤见 [容器部署说明](docs/container-deployment.md)。使用原生 systemd 发布时，见 [Gitea 原生部署](docs/gitea-deployment.md)。
|
||
|
||
完整部署、备份和回滚步骤见 [Ubuntu 部署说明](docs/migration-to-ubuntu.md)。配置和运行时数据与前端构建分开保存；本地现有数据库、主题文件和 Casdoor 配置不需要重建。
|
||
|
||
迁移前的静态页面、脚本和混淆工具已保存在项目内 `.legacy/`，不参与构建或运行，可用于核对历史内容。
|
||
|
||
主题上传支持最大 8 MB 的 `.qss` 和最大 4 MB 的 PNG/JPG 预览图，后端总请求体上限 16 MB。主题和打包文件一起保存；文件、元数据或预览更新后重新进入审核队列。退出时先停止接收请求，再关闭数据库。
|