chore: simplify deployment and exclude local planning docs

This commit is contained in:
2026-11-01 21:15:40 +08:00
parent a5018faff7
commit 0cea76de81
23 changed files with 34 additions and 944 deletions
+2
View File
@@ -1,4 +1,6 @@
/素材/
/plan.md
/DESIGN.md
node_modules/
dist/
-50
View File
@@ -1,50 +0,0 @@
# MirrorOUC 主题配色
## 参考与取值
2026-11-01 读取 [爱特工作室官网](https://www.itouc.cn/) 的浅色、暗色主题,并在浏览器中切换主题核对实际显示。
颜色以官网 [style.css](https://www.itouc.cn/wp-content/themes/ITStudioMainSite/style.css?ver=2.1.2) 的 CSS 变量和浏览器计算样式为准。Firecrawl branding 自动提取的颜色混入了图像颜色,不作为精确主题色的依据。
| 用途 | 浅色 | 暗色 | 官网变量 |
| --- | --- | --- | --- |
| 页面背景 | `#FFFFFF` | `#0D1117` | `--bg-body` |
| 次级背景、页脚 | `#F6F8FA` | `#161B22` | `--bg-surface` |
| 输入框、菜单、弹窗 | `#FFFFFF` | `#161B22` | `--bg-card` |
| 主要文字 | `#24292F` | `#C9D1D9` | `--text-primary` |
| 次级文字 | `#343A40` | `#6D737C` | `--text-secondary` |
| 链接、强调色 | `#0969DA` | `#58A6FF` | `--color-primary` |
| 边框 | `#D0D7DE` | `#30363D` | `--border-default` |
| 次级边框 | `#D8DEE4` | `#21262D` | `--border-muted` |
官网菜单阴影为 `0 4px 12px rgba(140,149,159,.15)` / `0 4px 12px rgba(0,0,0,.5)`,较大阴影为 `0 8px 24px rgba(140,149,159,.2)` / `0 8px 24px rgba(0,0,0,.8)`。
参考截图保存在本地忽略目录:
- [浅色参考](.local/screenshots/itouc-reference-light.jpg)
- [暗色参考](.local/screenshots/itouc-reference-dark.jpg)
## 在现有界面中的应用
- `src/style.css` 的 `:root` 和 `[data-theme='dark']` 集中定义颜色,沿用现有变量名。
- 页面与页头使用页面背景;输入框、主题菜单、弹窗使用卡片背景;页脚使用次级背景。页脚文字和校徽随主题切换。
- 镜像名称、公告、相关链接使用强调色;同步中的条目使用淡蓝色背景,失败条目使用淡红色背景,文字均沿用普通条目的颜色。
- 暗色主题的主标题、镜像表头及侧栏标题使用白色 `#FFFFFF`。
- 浅色失败色取官网 `--color-danger: #CF222E`。暗色红、绿、紫、橙分别取官网服务图标的 `#FF8A80`、`#6FDA83`、`#B9A0FF`、`#F5B04D`,适配暗底状态显示。这是 MirrorOUC 的组件映射,非官网同名状态组件。
- 实心按钮使用主题强调色;浅色按钮文字为白色,暗色为 `#0D1117`。悬停色由强调色混合 12% 黑色或白色生成,保证按钮文字清晰。
- 轻量悬停底色取强调色的 8% / 12% 透明度,弹窗遮罩使用中性黑色;这些是本项目的派生配色。
- 浏览器 `theme-color` 随主题更新为页面背景。
- 全站滚动条使用主题蓝色直条和透明轨道;Chromium/Safari 下宽度为 6px,隐藏默认箭头,Firefox 使用细滚动条。页面、菜单及弹窗统一使用此样式。
- 页头与页脚标识随主题切换:亮色使用 [mirrorOUC_dark.png](public/assets/mirrorOUC_dark.png),暗色使用 [mirrorOUC.png](public/assets/mirrorOUC.png),均直接显示原图。标识保持横向比例,手机端按可用宽度缩放。
- 浏览器标签页图标固定使用 [ouc-seal.png](public/assets/ouc-seal.png)。
- 页脚顶部背景分界线上方并排展示 [itstudio.png](public/assets/itstudio.png) 与 [ouc.png](public/assets/ouc.png),标识组合贴紧页面最右侧,底部与分界线对齐,宽度分别为 180px、210px,间距 21px,链接到各自官网,窄屏时按可用宽度缩小。暗色主题使用原图,浅色主题仅将字标区域覆盖为海大蓝,图形区域保留原色。
本次仅调整配色。MirrorOUC 现有的字体、字号、间距、组件尺寸、无分割线侧栏、桌面表格与公告对齐及手机单列布局继续沿用,不复制官网的首屏、服务图标或字体资源。海大校徽和发行版标识继续使用项目已有素材。
## 站点状态页
`/status` 按网络流量、磁盘状态、CPU / 内存、同步状态排列。图表使用现有主题变量、细网格和轻量面积填充,不添加渐变背景或装饰性指标卡;IPv4、IPv6 均只展示 HTTPS 和 rsync。
宽屏图表双列,900px 及以下单列;700px 及以下同步表转为纵向条目,图例在 480px 及以下保留当前与峰值,隐藏平均值。同步时间说明与时间值紧邻排列,桌面间距 12px,手机间距 8px;同步中与失败的行分别使用既有淡蓝、淡红背景。
图表支持时间范围、暂停刷新、曲线开关及鼠标、触摸、键盘查看时间点。数值、单位、时间格式和辅助说明全部来自语言文件,数据入口为演示模型,页头明确标注演示数据,后续可替换为真实监控接口。
+31 -68
View File
@@ -1,89 +1,52 @@
# MirrorOUC
中国海洋大学软件镜像源(MirrorOUC)网页界面
爱特软件镜像源的前端与管理服务,由[中国海洋大学爱特工作室](https://www.itouc.cn/)制作。使用 Vue 3、TypeScript 和 Go,支持镜像展示、公告、使用帮助与管理后台,同步任务由 [tunasync](https://github.com/tuna/tunasync) 执行。
本项目提供镜像检索、同步状态、使用帮助、软件下载及站点公告,并配套管理后台,用于维护站点内容、软件源配置和同步任务
## 部署
同步引擎采用 [TUNA tunasync](https://github.com/tuna/tunasync)
### 使用 Release
## 本地预览
从 [Releases](https://git.itouc.cn/ITStudio_OUC/OUCMirror-WebUI/releases) 下载与服务器系统、CPU 架构匹配的预编译包并解压。没有预编译部署包时,按下一节自行编译。
使用 Node.js 22.18 或更高版本:
部署目录只需包含:
```sh
```text
mirrorouc/
|-- mirrorouc # 后端程序
`-- dist/ # 前端构建产物
```
### 自行编译
需要 Node.js 22.18+ 和 Go 1.27+。在目标服务器或相同系统与架构的构建环境中,从项目根目录执行:
```bash
npm ci
npm run dev
npm run build
mkdir -p .local
go -C backend build -o ../.local/mirrorouc .
```
打开终端输出的地址,默认是 `http://127.0.0.1:5173/`。
将 `.local/mirrorouc` 与完整的 `dist/` 放到同一个部署目录,按下面的步骤启动。
```sh
npm run check:i18n # 检查中英文语言键与插值参数
npm run check:monitoring # 检查监控图表的数据夹具与资源总量约束
npm run check:directory # 构建后检查 Nginx 目录模板、翻译和资源
npm run build # TypeScript 检查与生产构建
npm run preview # 预览 dist 中的构建结果
```
## 对接 tunasync
## 当前界面
先启动 tunasync Manager 和 Worker,确认 Manager API 可访问,并取得 Worker 配置中 `[global].name` 对应的 ID。
Vue 3 + TypeScript + Vite,使用 vue-i18n 管理界面文案。当前首页支持镜像搜索、同步信息滚动动画、公告和帮助弹窗、亮色/暗色/跟随系统,以及中英文切换。语言和主题选择保存在当前浏览器。
在部署目录中,首次运行以下命令创建管理员,随机密码会输出到终端:
语言入口显示当前语言名称,点击后打开与站点主题一致的自定义下拉菜单;支持方向键、Home/End 定位、Enter/空格选择、Esc 取消,以及 Tab 离开。选项来自 `src/locales/index.ts` 中注册的语言,名称使用各语言文件的 `common.languageName`;注册新语言后,选择器、语言偏好恢复和镜像搜索会自动使用新的语言列表。
桌面端使用三列镜像列表与侧栏;手机端使用折叠导航。表格的后两列每 5 秒在「最近同步 + Size」与「下次同步 + Status」之间统一切换。表头每轮向上滚动一次,条目内容随机滚动 3~6 次后落定;使用系统的减少动态效果设置时直接显示最终值。页面隐藏时暂停轮换并取消未完成的动画。项目说明在悬浮提示及详情中查看。页脚使用宽幅分栏结构,在手机端纵向排列。新增页面也需兼顾手机端,并验证 320、390、768 和 1440 像素宽度下的中英文与明暗主题。
前台已接入真实后端,不会在连接失败时切换为演示数据。首页每 15 秒获取镜像状态,连接中断时保留上一次数据并显示提示。镜像名称直接打开 `/mirrors/<name>/`,使用帮助和公告通过 Markdown 安全渲染。公告只展示已发布内容;公告标题/正文和镜像使用说明均维护一份中文内容,切换界面语言时显示同一版。界面文案、镜像介绍及站点设置继续支持多语言。
`/status` 展示服务器实测 IPv4 / IPv6 HTTPS、rsync 流量,NFS 磁盘容量、IOPS、吞吐量以及 CPU / 内存;支持 1 / 6 / 24 小时范围,图表每 10 秒刷新,页面隐藏时暂停。同步明细另提供按仓库汇总的上游 TCP 拉取速度,约每 2 秒采样与刷新,并适配手机端。统计值从完整采样计算,曲线最多取 241 个点。桌面端图表双列,手机端单列,同步明细在窄屏改为纵向布局。未采集到的指标不会冒充为零。
`/admin` 提供登录、Markdown 公告草稿/发布、镜像展示信息与使用帮助、任务命令和日志、全局/单个镜像调度配置、站点标识/头像/首页相关链接/页脚友链/下载项、管理员和公告编辑账户,以及操作记录。同步间隔遵循 tunasync 的原生语义:从上次同步结束后开始计算,单位为分钟。任务命令只表示已提交,最终状态以 Worker 为准。
操作记录按时间倒序,每页 10 条;超过一页时显示分页控制,可查看全部历史记录。接口 `/api/v1/admin/audit?page=1` 返回当前页、总条数和总页数,未带 `page` 的旧版请求继续返回最近 200 条数组。
`/mirrors/<name>/` 采用与 TUNA 同类的 Nginx Fancyindex 方案,服务端直接返回包含完整文件列表、页头和页脚的 HTML。禁用 JavaScript 也可浏览目录、按名称/大小/修改时间排序和下载文件,不再请求目录 JSON。JavaScript 仅增强面包屑、当前目录搜索、每页 100 项、主题和语言选择;另有一次可选的站点设置请求,用于应用后台配置的品牌和页脚内容,失败不影响文件浏览。目录优先排列,隐藏项不展示,时间明确使用 UTC;文件保留原 URL、HEAD 和 Range 支持。在仓库根目录返回上级会回到首页。模板和表头文案从语言文件生成,默认中文,增强脚本支持语言切换。
## 后端与部署
后端使用 Go 标准库 HTTP、SQLite 和 TOML 解析器,不依赖数据库外部服务。详细部署、权限、备份和回退操作见 [deploy/README.md](deploy/README.md)。
```sh
# 需要 Go 1.27 或更高版本
cd backend
go mod download
go test ./...
go vet ./...
go build -o mirrorouc .
# 首次运行生成初始管理员密码,妥善保存终端输出
```bash
./mirrorouc -data ./data -init-admin admin
# 对接自己的 Manager 和 Worker;前端开发服务器已代理 /api 与 /uploads
./mirrorouc -data ./data -manager http://127.0.0.1:12345 -worker YOUR_WORKER_ID
```
生产构建通过 `-static ../dist` 或 `MIRROROUC_STATIC` 指定静态目录;`MIRROROUC_WORKER_CONFIG`、`MIRROROUC_LOGS`、`MIRROROUC_METRICS` 分别指定 Worker 配置、日志根目录和采样历史。缺少配置时,对应管理功能会显示不可用,不会启动假的同步引擎。管理页复用站点的明暗主题和语言选择。
然后启动服务,将 Manager 地址和 `YOUR_WORKER_ID` 替换为实际值:
镜像根目录通过 `deploy/nginx-preview.conf` 中两个 `alias /data/mirrors/` 配置。Go 不枚举镜像目录,也不代理文件内容。符号链接沿用 Nginx 和文件系统的访问规则,与镜像下载服务保持一致。
```bash
./mirrorouc -static ./dist -data ./data -manager http://127.0.0.1:12345 -worker YOUR_WORKER_ID
```
本地开发时,在被忽略的 `.env.local` 中设置 `MIRROROUC_NGINX_ORIGIN=http://100.69.2.2:8080`,再运行 Vite。目录 HTML、下载和其构建资源代理到该 Nginx;其他管理 API 继续代理到本地 Go 的 8081 端口。目录模板修改后需重新构建并更新 Nginx 使用的 `dist/`。未设置时,Nginx 地址默认为 `http://127.0.0.1:8080`。
默认监听 `127.0.0.1:8081`,可通过 `-listen` 修改。首页为 `/`,管理后台为 `/admin`,同步状态页为 `/status`。数据库与上传文件保存在 `data/`,更新时保留该目录。
当前服务器预览地址为 `http://100.69.2.2:8080`,管理入口 `/admin`,原有 80 端口下载服务保留。预览仅监听该 Tailnet 地址,正式域名与 HTTPS 尚未配置。
镜像目录与下载由已有的 Web 服务器提供,路径为 `/mirrors/<源名>/`。自定义目录页的 Fancyindex 模板随前端构建生成在 `dist/fancy-index/` 中。
## 源码约定
- `src/App.vue`:首页与弹窗交互。
- `directory.html`、`src/directory/`、`scripts/build-directory.ts`:服务端目录的 HTML 模板、渐进增强与构建,产物位于 `dist/fancy-index/`。
- `src/style.css`:爱特官网同款明暗配色、布局、动画和移动端样式;色值来源与映射见 [DESIGN.md](DESIGN.md)。
- `src/locales/zh-CN/`、`src/locales/en-US/`:界面文案及数据夹具文案;新增文案通过语言键引用。
- 各语言的 `mirrors.ts` 定义表头、状态、相对时间、容量与公告日期模板,`formats.ts` 定义日期和数字格式;组件通过 `t`、`d`、`n` 使用,不自行生成界面文案。
- `src/data.ts`:镜像类型与旧版界面数据夹具;生产页面通过 `src/usePublicData.ts` 和 `src/api.ts` 获取接口数据。
- `src/components/AdminPage.vue`、`src/locales/admin-messages.ts`:管理表单与中英文文案。
- `backend/`:鉴权、内容管理、tunasync 适配、配置预览与版本恢复、监控接口及集成测试。
- `deploy/`:systemd、Nginx、实测采集器与受限配置写入工具。
- `src/components/StatusPage.vue`、`MonitoringChart.vue`:监控布局、图表与同步明细交互;`src/monitoring.ts` 定义监控数据结构和演示曲线,`src/useMirrorFormats.ts` 复用首页与状态页的时间、容量格式。
- `public/assets/`:页面实际使用的素材。
根目录 `素材/` 是本地素材目录,已加入 `.gitignore`,不得提交;`node_modules/`、`dist/`、`.local/` 和环境变量文件同样不纳入 Git。
中国海洋大学软件镜像源(MirrorOUC)由[中国海洋大学爱特工作室](https://www.itouc.cn/)承建。
首页侧栏“相关链接”在后台「站点设置 → 首页相关链接」管理,支持多语言名称、站内/站外网址、使用帮助入口、增删与排序。它使用独立的 `relatedLinks` 配置;页脚友情链接继续使用 `links`。保存站点设置后,首页下次刷新或轮询即可生效。
需要本机监控采集或受限配置写入时,可按需对接 `backend/tools/` 中的工具。更多启动参数可通过 `./mirrorouc -help` 查看。
-110
View File
@@ -1,110 +0,0 @@
# MirrorOUC 部署
当前预览:`http://100.69.2.2:8080`,后台:`/admin`。这是单 Worker 适配版本,使用服务器现有的 tunasync Manager、Worker 和并行 rsync 配置,不重新安装或替换同步引擎。
## 运行结构
| 服务 | 位置与用途 |
| --- | --- |
| Nginx 预览 | 只监听 `100.69.2.2:8080`;原有 80 端口站点保持原配置 |
| mirrorouc.service | `mirrorouc` 普通用户,API 与静态文件监听 `127.0.0.1:8081` |
| mirrorouc-config.service | root 受限配置写入器,Unix socket 只允许 `mirrorouc` 组访问 |
| mirrorouc-metrics.timer | 每 10 秒采集 Linux CPU/内存、NFS `/data` I/O 和磁盘容量 |
| mirrorouc-counters.service | 添加独立 nftables 计数表,只计数,不修改已有规则、不丢弃数据包 |
| mirrorouc-speeds.service | 每约 2 秒读取 TCP 接收计数,按仓库汇总并行连接 |
| tunasync | 继续使用已有 Manager `127.0.0.1:12345` 与 Worker `srv-software-mirror` |
代码发布目录 `/opt/mirrorouc/releases/<release>`;`/opt/mirrorouc/current` 指向当前版本。业务数据库和上传图片保存在本地磁盘 `/var/lib/mirrorouc/`,不要放在 NFS 上。监控历史位于其 `metrics/history.json`,保留最近 24 小时;刚启动时没有完整 24 小时历史。
## 首次安装/更新
本地 Node.js 22.18+ 与 Go 1.27+:
```sh
npm ci
npm run check:i18n
npm run check:monitoring
npm run build
cd backend
go test ./...
go vet ./...
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -o ../mirrorouc .
```
把 `mirrorouc`、`dist/` 和 `deploy/` 放进新的 `/opt/mirrorouc/releases/<release>/`,确认二进制可执行。在 Debian 服务器上执行:
```sh
python3 /opt/mirrorouc/releases/<release>/deploy/test_config_helper.py
python3 /opt/mirrorouc/releases/<release>/deploy/test_job_speeds.py
sh /opt/mirrorouc/releases/<release>/deploy/install-metrics.sh
sh /opt/mirrorouc/releases/<release>/deploy/install-preview.sh /opt/mirrorouc/releases/<release>
systemctl status mirrorouc mirrorouc-config mirrorouc-metrics.timer
curl http://127.0.0.1:8081/healthz
nginx -t
```
安装脚本针对当前服务器路径。迁移到其他服务器时,应先调整 `nginx-preview.conf`、环境文件、配置写入器的固定路径与 Manager 地址。脚本不会清理旧发布目录或删除镜像文件。
首次安装会创建管理员 `admin`,随机密码写入 root 才能读取的 `/etc/mirrorouc/initial-admin-password`。本次部署的本地凭据文件为被 Git 忽略的 `.local/deployment/admin-credentials.json`。后台「账户」可修改当前密码,修改后所有旧会话失效。此密码文件不会跟随密码修改而更新。
环境配置文件 `/etc/mirrorouc/mirrorouc.env` 不随发布覆盖,权限 0600。正式启用 HTTPS 后将 `MIRROROUC_SECURE_COOKIES=true` 并重启服务;当前 Tailnet 预览通过 HTTP 访问,故为 false。登录 Cookie 为 HttpOnly、SameSite=Strict,有效期 12 小时;写入接口另需会话 CSRF Token 与同源请求。
## 配置发布和权限
Web 服务不能直接写 `/etc/tunasync`。配置写入器固定只接受 `/etc/tunasync/worker.conf` 和 `/etc/tunasync/mirrors.d/*.conf`:
- 全局只可修改 concurrent、interval、retry、timeout。
- 已有镜像只可修改 upstream、interval、retry、timeout。自定义 command、rsync_options、provider 等字段必须保留。
- 新增只支持 rsync/two-stage-rsync,文件名固定为 `mirrorouc-<name>.conf`;不接受任意 Shell 命令。
- 编辑前后均验证 TOML、数值、上游地址和文件内容哈希。产生冲突时拒绝覆盖。
- 先生成可阅读的完整文件前后预览,再由管理员确认应用;应用失败恢复原文件并尝试重新加载。
- SQLite 保留变更版本与审计记录;应用过的变更可以恢复至变更前,若文件已被其他修改覆盖则拒绝恢复。
- 写入器保留待完成事务日志 `/var/lib/mirrorouc-config/pending.json`;若进程在写入中退出,下次启动恢复原文件。若恢复失败则拒绝继续写入,需要运维检查该文件与 Worker 状态。
Manager 返回成功表示 reload 命令已提交,并不等于 Worker 已完成重载,需查看 Worker 服务和任务状态。已有仓库禁用后用「开始同步」重新启动;tunasync 不提供单独的 enable 命令。
## 监控口径
HTTPS/rsync 使用 TCP 443/873 的 IPv4、IPv6 收发字节计数,双向合计,排除回环接口。8080/80 端口的 HTTP 预览流量不计入 HTTPS,也不展示 HTTP 曲线。没有经过这些端口的流量不会被推算进对应协议。没有有效采样时显示等待采集。
`/status` 同步明细的「拉取速度」来自 Linux TCP_INFO 的 `bytes_received`,通过 `ss -tinpeH` 读取,关联 `tunasync-worker.service` 的进程与仓库目标路径,并追溯 git/ssh 等辅助进程的父进程。多个 rsync 子进程共享同一个 socket 时按 inode/socket cookie 去重,多个并行连接求和;约每 2 秒采样并刷新,单位 B/s、KB/s、MB/s、GB/s。只计算 TCP 接收,不把上传量、NFS I/O 或磁盘写入速度当作拉取速度。
这是采样窗口的接收速率,采样间建立并关闭的短连接可能漏记,不作为精确流量计费数据。首次采样不使用连接生存期累计值冒充瞬时速度。仅同步中的仓库显示数值;有效采样中的零表示当时没有收到数据,未同步/采样失败/数据过期时显示「—」。数据超过 15 秒即失效。相关原始字段见 [Linux TCP_INFO](https://github.com/torvalds/linux/blob/master/include/uapi/linux/tcp.h) 和 [iproute2 ss](https://github.com/iproute2/iproute2/blob/main/misc/ss.c)。
NFS I/O 来自 `/proc/self/mountstats` 的 `/data` 挂载,磁盘容量来自 statvfs;CPU、内存来自 `/proc`。采样历史仅覆盖采集器启用后的时间,不补造旧数据。图表最多展示 241 个采样点,均值、当前值、峰值从当前窗口全部原始有效采样计算。
目录 HTML、静态资源和文件下载全部由 Nginx 提供,Go 不参与目录遍历或文件传输。需要与当前 Nginx ABI 匹配的 Fancyindex 模块及内置 addition、sub_filter 模块;当前 Debian 13 使用 `apt-get install libnginx-mod-http-fancyindex`,安装后执行 `nginx -t`。自编译 Nginx 必须安装匹配模块,不要用包管理器覆盖现有二进制。主配置须加载模块(Debian 的 `/etc/nginx/modules-enabled/*.conf`)。
`npm run build` 使用独立 Vite 入口 `directory.html`,随后生成 `dist/fancy-index/header.html`、`footer.html` 和 `labels.conf`。Fancyindex 内部子请求插入页头和页脚,`sub_filter` 用语言文件生成的文案替换四个原生英文标签。浏览器首次响应已经包含全部文件条目;无需 JavaScript、Go 或 JSON 即可导航和下载。JS 只增加搜索、每页 100 条、面包屑、主题、语言和一次可选的站点设置加载。无 JS 时默认中文,显示全部条目。目录 GET/HEAD 只读、目录优先、隐藏项省略,时间显示 UTC;表头的排序链接由 Fancyindex 在服务端处理。
目录正则 location 的 `alias /data/mirrors/$mirror_directory` 与下载 location 的 `alias /data/mirrors/` 指向同一镜像树;符号链接遵循 Nginx 和文件系统访问规则,镜像树应仅包含可公开分发的内容。`/mirrors/` 重定向首页,因此仓库根目录的原生上级链接也会返回首页。目录仍需读取当前层文件元数据,不递归扫描;服务端 HTML 不会消除 NFS 元数据开销,大目录首访延迟仍需单独监测。
文件响应继续设置 CSP sandbox 和 nosniff,避免仓库中的 HTML/脚本获得管理页面同源权限。目录 HTML 使用主站 CSP,两个模板子请求入口为 `internal`,不能直接访问。仓库中的 `index.html` 不会替代目录列表;显式访问它仍走文件下载 location,保留 sandbox、HEAD 和 Range。
发布时同时更新整个 `dist/` 和 `nginx-preview.conf`,保证 `labels.conf` 在 `nginx -t` 时已经存在。执行检查后 reload Nginx;只有前端和目录变化时不必重启 Go 或 tunasync。旧 `/api/v1/directory/` 已移除,原 `MIRROROUC_MIRRORS` 环境变量不再使用。不重新初始化数据库或修改同步任务,原有 80 端口站点保持原配置。回退时同时恢复站点配置与发布目录软链接,并重新检查、reload。
## 备份与回退
日常备份包括 SQLite、`uploads/`、`/etc/mirrorouc/` 和 `/etc/tunasync/`。数据库运行时使用 SQLite backup API 或 `sqlite3 ... '.backup ...'`;直接复制数据库文件前先停止 `mirrorouc.service`,同时处理 WAL 文件。备份文件包含账户哈希、会话和可能带内部地址的配置,应限制读取权限。
应用版本回退:将 `/opt/mirrorouc/current` 指回旧发布目录,再 `systemctl restart mirrorouc`。本次新增数据库表使用 `CREATE TABLE IF NOT EXISTS`;未来若出现不兼容数据库迁移,需要同时恢复对应数据库备份。
只撤下预览时,删除 `/etc/nginx/sites-enabled/mirrorouc-preview`,通过 `nginx -t` 后 reload Nginx,并停止 `mirrorouc.service` 与 `mirrorouc-config.service`。这不会修改原有 80 端口镜像站点。停止新增采集器不会影响 tunasync;若需要删除计数表,只删除 `inet mirrorouc_monitor`,不要 flush 全局 nftables 规则。
## 验证范围
`backend/*_test.go` 使用临时数据库与假的 Manager,覆盖鉴权、角色、CSRF、草稿隔离、并发冲突、任务提交、配置应用/恢复、上游不可用缓存、图片校验及监控统计。`test_config_helper.py` 独立验证写入白名单、自定义命令保留、注入拒绝与失败恢复,不操作真实同步配置。
本次部署核验真实 API、镜像目录、日志、监控与后台草稿保存。没有为验证效果而停止、重启仓库,或应用修改后的生产同步参数。
先运行 `npm run build && npm run check:directory`,再在安装 Fancyindex 的 Linux 上运行 `python3 deploy/test_nginx_directory.py`。测试使用临时文件与独立本地端口,Go 上游故意不可用,验证原始 HTML 包含条目、中英文标签模板、排序、特殊文件名转义、空/不存在目录、仓库 index.html、HEAD/Range、只读限制、内部模板隔离和路径边界;不停止真实服务或修改真实镜像目录。
## 统一中文内容升级
公告的 title/body 和镜像的 help 已改为单个字符串,所有界面语言共用中文内容。旧版本的语言映射在服务启动时以事务迁移:优先保留 zh-CN,其次 zh;没有中文键的历史记录保留原内容供管理员整理。原始 JSON 保存在 SQLite 的 shared_content_backups 表,迁移会递增记录 revision,避免旧编辑页面覆盖新内容;重复启动不会重复迁移。
此次内容格式升级需要在回退旧应用时同时恢复升级前的数据库备份。部署前使用 SQLite backup API 生成一致性快照,备份目录仅 root 可读。迁移不修改镜像介绍、站点文案或同步配置。
## 首页相关链接
`settings/site` 的 `relatedLinks` 独立控制首页侧栏,与页脚 `links` 分开。旧设置缺少该字段时,接口补充原有的三个入口,不改写数据库。显式保存空数组会隐藏该栏目;仍打开旧版表单的客户端提交时,若未携带该字段,后端保留当前已保存的相关链接。条目支持 `kind=help` 的站内使用帮助与 `kind=url` 的 HTTP(S)/站内绝对路径;不接受脚本、data URL、协议相对地址或反斜杠路径。名称支持多语言,数组顺序即显示顺序。
-5
View File
@@ -1,5 +0,0 @@
#!/bin/sh
set -eu
if ! /usr/sbin/nft list table inet mirrorouc_monitor >/dev/null 2>&1; then
/usr/sbin/nft -f /etc/mirrorouc/protocol-counters.nft
fi
-23
View File
@@ -1,23 +0,0 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")"
if ! id mirrorouc >/dev/null 2>&1; then
useradd --system --home-dir /var/lib/mirrorouc --shell /usr/sbin/nologin mirrorouc
fi
install -d -o mirrorouc -g mirrorouc -m 0700 /var/lib/mirrorouc
install -d -o root -g mirrorouc -m 0750 /var/lib/mirrorouc/metrics
install -d -o root -g root -m 0755 /usr/local/lib/mirrorouc
install -d -o root -g root -m 0755 /etc/mirrorouc
install -m 0644 collect_metrics.py /usr/local/lib/mirrorouc/collect_metrics.py
install -m 0644 collect_job_speeds.py /usr/local/lib/mirrorouc/collect_job_speeds.py
install -m 0755 ensure-counters.sh /usr/local/lib/mirrorouc/ensure-counters.sh
install -m 0644 protocol-counters.nft /etc/mirrorouc/protocol-counters.nft
install -m 0644 mirrorouc-counters.service mirrorouc-metrics.service mirrorouc-metrics.timer mirrorouc-speeds.service /etc/systemd/system/
if ! /usr/sbin/nft list table inet mirrorouc_monitor >/dev/null 2>&1; then
/usr/sbin/nft -c -f /etc/mirrorouc/protocol-counters.nft
fi
systemctl daemon-reload
systemctl enable --now mirrorouc-counters.service mirrorouc-metrics.timer
systemctl start mirrorouc-metrics.service
systemctl enable --now mirrorouc-speeds.service
systemctl restart mirrorouc-speeds.service
-53
View File
@@ -1,53 +0,0 @@
#!/bin/sh
# Run as root: sh deploy/install-preview.sh /opt/mirrorouc/releases/<release>
set -eu
release=$(readlink -f "$1")
case "$release" in /opt/mirrorouc/releases/*) ;; *) echo 'Invalid release path' >&2; exit 1;; esac
test -x "$release/mirrorouc"
test -f "$release/dist/index.html"
test -f "$release/dist/fancy-index/header.html"
test -f "$release/dist/fancy-index/footer.html"
# The module must match the installed Nginx ABI; do not replace a custom build.
if ! nginx -T 2>&1 | grep -q 'load_module.*ngx_http_fancyindex_module'; then
echo 'Install and enable a matching Nginx Fancyindex module first (Debian: apt-get install libnginx-mod-http-fancyindex).' >&2
exit 1
fi
deploy="$release/deploy"
id mirrorouc >/dev/null 2>&1 || useradd --system --home-dir /var/lib/mirrorouc --shell /usr/sbin/nologin mirrorouc
install -d -m 0700 -o mirrorouc -g mirrorouc /var/lib/mirrorouc
install -d -m 0755 /etc/mirrorouc /usr/local/lib/mirrorouc
install -d -m 0700 /var/lib/mirrorouc-config
install -m 0755 "$deploy/config-helper.py" /usr/local/lib/mirrorouc/config-helper.py
install -m 0644 "$deploy/mirrorouc.service" "$deploy/mirrorouc-config.service" /etc/systemd/system/
if [ ! -f /etc/mirrorouc/mirrorouc.env ]; then
umask 077
cat > /etc/mirrorouc/mirrorouc.env <<'EOF'
MIRROROUC_LISTEN=127.0.0.1:8081
MIRROROUC_DATA=/var/lib/mirrorouc
MIRROROUC_STATIC=/opt/mirrorouc/current/dist
MIRROROUC_MANAGER=http://127.0.0.1:12345
MIRROROUC_WORKER=srv-software-mirror
MIRROROUC_WORKER_CONFIG=/etc/tunasync/worker.conf
MIRROROUC_LOGS=/var/log/tunasync
MIRROROUC_METRICS=/var/lib/mirrorouc/metrics/history.json
MIRROROUC_CONFIG_SOCKET=/run/mirrorouc-config/control.sock
MIRROROUC_SECURE_COOKIES=false
EOF
fi
# Leave current tunasync configurations, ownership and permissions intact.
if [ ! -s /var/lib/mirrorouc/mirrorouc.db ]; then
umask 077
runuser -u mirrorouc -- "$release/mirrorouc" -data /var/lib/mirrorouc -init-admin admin > /etc/mirrorouc/initial-admin-password
fi
ln -sfn "$release" /opt/mirrorouc/current.new
mv -Tf /opt/mirrorouc/current.new /opt/mirrorouc/current
install -m 0644 "$deploy/nginx-preview.conf" /etc/nginx/sites-available/mirrorouc-preview
ln -sfn /etc/nginx/sites-available/mirrorouc-preview /etc/nginx/sites-enabled/mirrorouc-preview
nginx -t
systemctl daemon-reload
systemctl enable --now mirrorouc-config.service
systemctl restart mirrorouc-config.service
systemctl enable mirrorouc.service
systemctl restart mirrorouc.service
systemctl reload nginx
echo 'MirrorOUC preview installed at http://100.69.2.2:8080'
-25
View File
@@ -1,25 +0,0 @@
[Unit]
Description=MirrorOUC restricted tunasync configuration writer
After=tunasync-manager.service
[Service]
ExecStart=/usr/bin/python3 /usr/local/lib/mirrorouc/config-helper.py
Restart=on-failure
RestartSec=5
RuntimeDirectory=mirrorouc-config
RuntimeDirectoryMode=0755
StateDirectory=mirrorouc-config
StateDirectoryMode=0700
UMask=0077
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/etc/tunasync /var/lib/mirrorouc-config /run/mirrorouc-config
ProtectKernelTunables=true
ProtectControlGroups=true
RestrictSUIDSGID=true
RestrictAddressFamilies=AF_UNIX AF_INET
[Install]
WantedBy=multi-user.target
-9
View File
@@ -1,9 +0,0 @@
[Unit]
Description=MirrorOUC passive protocol byte counters
After=nftables.service
[Service]
Type=oneshot
ExecStart=/usr/local/lib/mirrorouc/ensure-counters.sh
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
-13
View File
@@ -1,13 +0,0 @@
[Unit]
Description=MirrorOUC read-only host metrics collection
[Service]
Type=oneshot
User=root
Group=mirrorouc
ExecStart=/usr/bin/python3 /usr/local/lib/mirrorouc/collect_metrics.py
UMask=0027
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/var/lib/mirrorouc/metrics
ProtectHome=true
PrivateTmp=true
-8
View File
@@ -1,8 +0,0 @@
[Unit]
Description=Collect MirrorOUC metrics every 10 seconds
[Timer]
OnBootSec=10
OnUnitActiveSec=10
AccuracySec=1
[Install]
WantedBy=timers.target
-22
View File
@@ -1,22 +0,0 @@
[Unit]
Description=MirrorOUC per-mirror upstream TCP receive rates
After=tunasync-worker.service
[Service]
User=root
Group=mirrorouc
ExecStart=/usr/bin/python3 /usr/local/lib/mirrorouc/collect_job_speeds.py
Restart=on-failure
RestartSec=3
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadWritePaths=/var/lib/mirrorouc/metrics
ProtectKernelTunables=true
ProtectControlGroups=true
RestrictAddressFamilies=AF_UNIX AF_NETLINK AF_INET AF_INET6
[Install]
WantedBy=multi-user.target
-26
View File
@@ -1,26 +0,0 @@
[Unit]
Description=MirrorOUC web and administration API
After=network.target tunasync-manager.service mirrorouc-config.service
Wants=mirrorouc-config.service
[Service]
User=mirrorouc
Group=mirrorouc
WorkingDirectory=/opt/mirrorouc/current
EnvironmentFile=/etc/mirrorouc/mirrorouc.env
ExecStart=/opt/mirrorouc/current/mirrorouc
Restart=on-failure
RestartSec=5
UMask=0077
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/mirrorouc
ProtectKernelTunables=true
ProtectControlGroups=true
RestrictSUIDSGID=true
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
[Install]
WantedBy=multi-user.target
-67
View File
@@ -1,67 +0,0 @@
server {
listen 100.69.2.2:8080;
server_name 100.69.2.2;
client_max_body_size 5m;
location = /mirrors {
return 302 /;
}
location = /mirrors/ {
return 302 /;
}
location /assets/ {
root /opt/mirrorouc/current/dist;
try_files $uri =404;
add_header X-Content-Type-Options nosniff always;
}
# Fancyindex renders the complete directory on the server. No Go/JSON hop.
location ~ ^/mirrors/(?<mirror_directory>.+/)$ {
alias /data/mirrors/$mirror_directory;
index .mirrorouc-autoindex-only;
fancyindex on;
fancyindex_header /_directory/header.html;
fancyindex_footer /_directory/footer.html;
fancyindex_show_path off;
fancyindex_name_length 256;
fancyindex_exact_size off;
fancyindex_directories_first on;
fancyindex_show_dotfiles off;
fancyindex_localtime off;
fancyindex_time_format "%Y-%m-%d %H:%M:%S UTC";
include /opt/mirrorouc/current/dist/fancy-index/labels.conf;
charset utf-8;
limit_except GET { deny all; }
add_header Cache-Control no-cache;
add_header X-Content-Type-Options nosniff always;
add_header X-Frame-Options DENY always;
add_header Referrer-Policy same-origin always;
add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; connect-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'" always;
}
# Only Fancyindex subrequests may read the generated fragments.
location = /_directory/header.html {
internal;
alias /opt/mirrorouc/current/dist/fancy-index/header.html;
}
location = /_directory/footer.html {
internal;
alias /opt/mirrorouc/current/dist/fancy-index/footer.html;
}
location /mirrors/ {
alias /data/mirrors/;
autoindex off;
add_header X-Content-Type-Options nosniff always;
add_header Content-Security-Policy "sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src 'self' data:" always;
}
location / {
proxy_pass http://127.0.0.1:8081;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 35s;
}
}
-25
View File
@@ -1,25 +0,0 @@
# Passive accounting only; no existing rules or tables are flushed.
table inet mirrorouc_monitor {
counter https4 { }
counter https6 { }
counter rsync4 { }
counter rsync6 { }
chain account {
meta nfproto ipv4 tcp sport 443 counter name https4
meta nfproto ipv4 tcp dport 443 tcp sport != 443 counter name https4
meta nfproto ipv6 tcp sport 443 counter name https6
meta nfproto ipv6 tcp dport 443 tcp sport != 443 counter name https6
meta nfproto ipv4 tcp sport 873 counter name rsync4
meta nfproto ipv4 tcp dport 873 tcp sport != 873 counter name rsync4
meta nfproto ipv6 tcp sport 873 counter name rsync6
meta nfproto ipv6 tcp dport 873 tcp sport != 873 counter name rsync6
}
chain input {
type filter hook input priority 300; policy accept;
iifname != "lo" jump account
}
chain output {
type filter hook output priority 300; policy accept;
oifname != "lo" jump account
}
}
-151
View File
@@ -1,151 +0,0 @@
"""Exercise the shipped Nginx routes using disposable files and an isolated port."""
from html.parser import HTMLParser
from pathlib import Path
import shutil
import socket
import subprocess
import tempfile
import time
import unittest
import urllib.error
import urllib.parse
import urllib.request
class NginxDirectoryTests(unittest.TestCase):
@classmethod
def setUpClass(cls):
nginx = shutil.which('nginx')
if not nginx:
raise unittest.SkipTest('Nginx is required for the integration fixture')
cls.temp = tempfile.TemporaryDirectory(prefix='mirrorouc-nginx-test-')
cls.root = Path(cls.temp.name)
cls.mirrors = cls.root / 'mirrors'
cls.dist = cls.root / 'dist'
(cls.mirrors / 'repo' / 'sub').mkdir(parents=True)
(cls.mirrors / 'repo' / 'empty').mkdir()
build = Path(__file__).resolve().parent.parent / 'dist'
if not (build / 'fancy-index' / 'header.html').is_file():
raise RuntimeError('Run npm run build before the Nginx integration fixture')
shutil.copytree(build, cls.dist)
(cls.dist / 'assets' / 'test.js').write_text('window.fixture = true', encoding='utf-8')
(cls.mirrors / 'repo' / 'index.html').write_text('repository index must not replace listing', encoding='utf-8')
(cls.mirrors / 'repo' / '中文 #+%.txt').write_bytes(b'0123456789abcdef')
(cls.mirrors / 'repo' / 'zero').write_bytes(b'')
(cls.mirrors / 'repo' / '.hidden').write_text('hidden', encoding='utf-8')
(cls.mirrors / 'repo' / '\"><img src=x onerror=alert(1)>.txt').write_text('escaped name', encoding='utf-8')
(cls.root / 'private-secret').write_text('outside-secret', encoding='utf-8')
with socket.socket() as available:
available.bind(('127.0.0.1', 0))
port = available.getsockname()[1]
cls.base = f'http://127.0.0.1:{port}'
server = Path(__file__).with_name('nginx-preview.conf').read_text(encoding='utf-8')
server = server.replace('listen 100.69.2.2:8080;', f'listen 127.0.0.1:{port};')
server = server.replace('/data/mirrors/', cls.mirrors.as_posix() + '/')
server = server.replace('/opt/mirrorouc/current/dist', cls.dist.as_posix())
# The Go upstream is deliberately unavailable throughout these tests.
server = server.replace('http://127.0.0.1:8081', 'http://127.0.0.1:9')
config = cls.root / 'nginx.conf'
config.write_text(f'load_module /usr/lib/nginx/modules/ngx_http_fancyindex_module.so;\nworker_processes 1;\npid {cls.root}/nginx.pid;\nerror_log {cls.root}/error.log;\nevents {{ worker_connections 32; }}\nhttp {{ access_log off; types {{ text/html html; text/plain txt; application/javascript js; }}\n{server}\n}}\n', encoding='utf-8')
validation = subprocess.run([nginx, '-p', str(cls.root), '-c', str(config), '-t'], capture_output=True, text=True)
if validation.returncode:
raise RuntimeError(validation.stderr)
cls.process = subprocess.Popen([nginx, '-p', str(cls.root), '-c', str(config), '-g', 'daemon off; master_process off;'], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
for _ in range(100):
if cls.process.poll() is not None:
raise RuntimeError((cls.root / 'error.log').read_text())
try:
with urllib.request.urlopen(cls.base + '/assets/test.js', timeout=1):
return
except (OSError, urllib.error.URLError):
time.sleep(0.03)
cls.process.terminate()
raise RuntimeError('Isolated Nginx did not become ready')
@classmethod
def tearDownClass(cls):
cls.process.terminate()
cls.process.wait(timeout=5)
cls.temp.cleanup()
def request(self, path, method='GET', headers=None):
request = urllib.request.Request(self.base + path, method=method, headers=headers or {})
try:
response = urllib.request.build_opener(NoRedirect).open(request, timeout=5)
except urllib.error.HTTPError as response:
return response.code, response.headers, response.read()
with response:
return response.status, response.headers, response.read()
def test_complete_server_html_without_go_or_javascript(self):
code, headers, body = self.request('/mirrors/repo/')
self.assertEqual(code, 200)
self.assertIn('text/html', headers['Content-Type'])
html = body.decode('utf-8')
self.assertIn('<table id="list">', html)
self.assertIn('href="sub/"', html)
self.assertIn('href="index.html"', html)
self.assertIn('中文 #+%.txt', html)
self.assertIn('data-i18n="directory.name">文件名</span>', html)
self.assertIn('data-i18n="directory.parent">返回上级</span>', html)
self.assertIn('UTC', html)
self.assertIn('</footer>', html)
self.assertNotIn('{{', html)
self.assertNotIn('repository index must not replace listing', html)
self.assertNotIn('.hidden', html)
parsed = Tags(); parsed.feed(html)
self.assertFalse(any(tag == 'img' and attrs.get('onerror') for tag, attrs in parsed.tags))
self.assertNotIn('sandbox', headers['Content-Security-Policy'])
self.assertEqual(self.request('/assets/test.js')[0], 200)
self.assertEqual(self.request('/')[0], 502)
def test_files_still_support_range_and_head(self):
url = '/mirrors/repo/' + urllib.parse.quote('中文 #+%.txt', safe='')
code, headers, body = self.request(url, headers={'Range': 'bytes=1-4'})
self.assertEqual((code, body), (206, b'1234'))
self.assertEqual(headers['Content-Range'], 'bytes 1-4/16')
self.assertIn('sandbox', headers['Content-Security-Policy'])
self.assertEqual(headers['X-Content-Type-Options'], 'nosniff')
code, headers, body = self.request(url, method='HEAD')
self.assertEqual((code, int(headers['Content-Length']), body), (200, 16, b''))
def test_empty_missing_internal_and_parent(self):
code, _, body = self.request('/mirrors/repo/empty/')
self.assertEqual(code, 200)
self.assertIn(b'<table id="list">', body)
self.assertEqual(self.request('/mirrors/missing/')[0], 404)
self.assertEqual(self.request('/mirrors/repo/', method='POST')[0], 403)
self.assertEqual(self.request('/_directory/header.html')[0], 404)
self.assertEqual(self.request('/_directory/footer.html')[0], 404)
code, headers, _ = self.request('/mirrors/')
self.assertEqual(code, 302)
self.assertTrue(headers['Location'].endswith('/'))
code, _, body = self.request('/mirrors/%2e%2e/private-secret/')
self.assertNotEqual(code, 200)
self.assertNotIn(b'outside-secret', body)
def test_native_sort_links_and_head(self):
code, _, body = self.request('/mirrors/repo/?C=N&O=D')
self.assertEqual(code, 200)
html = body.decode('utf-8')
self.assertLess(html.index('href="sub/'), html.index('href="empty/'))
code, _, body = self.request('/mirrors/repo/', method='HEAD')
self.assertEqual((code, body), (200, b''))
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
class Tags(HTMLParser):
def __init__(self):
super().__init__()
self.tags = []
def handle_starttag(self, tag, attrs):
self.tags.append((tag, dict(attrs)))
if __name__ == '__main__':
unittest.main()
-288
View File
@@ -1,288 +0,0 @@
## 已确定的方向
> 实现进度:前台、Go HTTP + SQLite 管理服务及 Vue 管理页面已接入。当前预览部署、使用方式与实际权限边界以 [README.md](README.md) 和 [deploy/README.md](deploy/README.md) 为准;下文保留原始方案。
- 使用 Vue 3、TypeScript 和 Vite 开发前端。
- 使用 vue-i18n,所有界面文案通过语言键引用语言文件。
- 第一版支持简体中文(`zh-CN`)和英文(`en-US`)。
- 支持亮色、暗色以及跟随系统的主题设置。
- 界面配色沿用爱特工作室官网:浅色强调蓝 `#0969DA`,暗色强调蓝 `#58A6FF`;完整色值见 [DESIGN.md](DESIGN.md)。
- 以紧凑、清晰的镜像列表为首页主体,融入中国海洋大学的海洋特色。
- 借鉴机场航班信息屏,在同步状态与时间字段变化时使用向上滚动动效。
- 根目录的 `素材/` 仅用于本地素材整理,不纳入 Git。
## 界面设计
### 布局与视觉
首页采用宽列表、窄侧栏的布局。顶部保留站点标识、主要导航、语言选择和主题切换,主体优先展示搜索与镜像列表。
```text
校徽 / MirrorOUC 使用帮助 公告 同步状态 关于 语言 主题
中国海洋大学软件镜像源
搜索镜像…… 全部 / 发行版 / 软件仓库 / 其他
镜像名称 最近同步 / 下次同步 Size / Status │ 站点公告
ubuntu 12 分钟前 / — 3.4 TB / 同步中 │ 常用下载
debian 35 分钟前 / 25 分钟后 4.2 TB / 已同步 │ 使用帮助
archlinux 58 分钟前 / 即将开始 1.3 TB / 等待同步│ 相关链接
…… │
中国海洋大学软件镜像源(MirrorOUC)由中国海洋大学爱特工作室承建。
```
上述名称、状态和时间仅用于说明布局,不表示本站实际提供的镜像或运行状态。
亮色主题使用白底、浅灰面板和蓝色重点元素;暗色主题使用 `#0D1117` 背景与 `#161B22` 面板。文字、边框及页脚与爱特工作室官网主题保持一致,品牌通过海大校徽呈现。
主体采用规整表格、细分隔线和克制的圆角。避免大面积渐变、玻璃效果、堆叠装饰卡片、空泛标语及无意义的小字脚注。正文优先使用系统字体,镜像名称与时间数字可使用等宽字体或等宽数字。
移动端同样保留三列及统一轮换机制;帮助、下载和公告入口仍应易于访问。
### 同步动效
- 后两列表头和条目共用一个 5 秒周期,在「最近同步 + Size」与「下次同步 + Status」之间切换。
- 表头每轮向上滚动一次;条目随机滚动 3~6 次,在约一秒内落定至正确值。
- 保持行高、列宽和列表顺序稳定,不因后台状态刷新自动重排列表。
- 同步中的条目使用淡蓝色背景,同步失败的条目使用淡红色背景,文字均沿用普通颜色。
- 支持系统的减少动态效果设置,后台标签页暂停动画和频繁刷新。
- 保证键盘操作、文本选择、屏幕阅读器和英文布局可用,状态不能只依赖颜色表达。
独立的同步状态页面可进一步提供大屏模式,集中展示正在执行和即将执行的任务。首页保持便于查找和点击的列表形式。
## 功能规划
### 公共网站
| 功能 | 计划内容 |
| --- | --- |
| 镜像列表 | 按名称、别名和中文描述搜索,按分类筛选,进入目录或查看帮助 |
| 同步状态 | 展示当前状态、最近成功同步时间、下次计划时间及可获得的镜像大小 |
| 使用帮助 | Markdown 文档、配置示例、代码高亮与复制 |
| 常用下载 | 常见发行版安装镜像和软件安装包的下载入口 |
| 站点公告 | 公告列表、详情、置顶和维护通知 |
| 关于与友链 | 承建信息、联系方式和相关站点链接 |
| 主题与语言 | 独立选择并保存主题、界面语言 |
同步状态与文件可用性分别表达。一次同步失败不直接等同于现有镜像文件不可下载,页面同时保留最近成功同步时间。进度百分比、传输速率等信息,仅在具有可靠数据来源时展示。
### 管理后台
| 模块 | 计划内容 |
| --- | --- |
| 公告与帮助 | Markdown 编辑、预览、草稿、发布、置顶;公告与镜像帮助统一中文内容 |
| 镜像信息 | 名称、分类、描述、帮助关联、公开状态与下载入口 |
| 同步配置 | 上游、同步方式、同步间隔、重试、超时及并发设置 |
| 任务操作 | 手动触发、停止、执行结果、日志和同步历史 |
| 站点设置 | 网站头像/标识、明暗主题 Logo、友链、联系方式和承建信息 |
| 账号与记录 | 管理员登录、内容与运维权限划分、操作记录 |
镜像是否公开展示与同步任务是否启用分别管理。Markdown 渲染应过滤不安全内容,公开接口只返回适合对外展示的信息。
## 国际化约定
### 界面文案
公开网站与管理后台统一使用 vue-i18n。导航、按钮、标题、占位提示、工具提示、校验错误、确认弹窗、空状态、加载状态、无障碍标签及页面标题,都必须从语言文件读取。
使用稳定、语义化的语言键,例如:
```vue
<script setup lang="ts">
import { useI18n } from 'vue-i18n'
const { t } = useI18n()
</script>
<template>
<button>{{ t('common.save') }}</button>
<span>{{ t('mirrors.status.syncing') }}</span>
</template>
```
语言文件按语言和功能模块划分,以下为计划结构:
```text
src/locales/
├── index.ts
├── zh-CN/
│ ├── common.ts
│ ├── site.ts
│ ├── mirrors.ts
│ ├── announcements.ts
│ └── admin.ts
└── en-US/
├── common.ts
├── site.ts
├── mirrors.ts
├── announcements.ts
└── admin.ts
```
例如,`zh-CN/mirrors.ts` 导出 `mirrors` 命名空间对应的内容:
```ts
export default {
status: {
syncing: '同步中',
success: '已同步',
},
nextSync: '下次同步:{time}',
}
```
对应的 `en-US/mirrors.ts`:
```ts
export default {
status: {
syncing: 'Syncing',
success: 'Synced',
},
nextSync: 'Next sync: {time}',
}
```
开发时遵循以下规则:
- 组件中不硬编码可翻译文案,也不通过拼接词语生成句子;使用完整句子的参数插值。
- 使用 TypeScript 约束语言键,并检查各语言的键、插值参数是否一致。
- 使用 vue-i18n 和 `Intl` 格式化日期、相对时间、数字及复数,不手动拼接“分钟前”等单位。
- 后端返回稳定的状态码、错误码、参数和时间戳,前端映射为本地化文案。
- 不直接将后端原始错误文本展示为公共页面提示;运维日志在管理后台单独查看。
- 软件名称、仓库标识、网址、文件名、命令和用户输入保持原值。
- 滚动组件应适应不同语言的文字长度,并在减少动态效果模式下直接更新文本。
### 语言选择与回退
语言选择顺序为:用户保存的选择 → 匹配浏览器语言 → 简体中文。浏览器区域语言需映射到支持的语言,例如 `en-GB` 匹配 `en-US`。
缺少界面译文时回退至简体中文,同时在开发和检查流程中暴露缺失项。切换语言后同步更新文档的 `lang` 属性、页面标题和相关无障碍标签。
语言偏好与主题偏好独立保存。语言与时区也分别处理,切换语言不应改变时间戳所代表的实际时刻;需要展示固定调度时间时明确标注时区。
### 动态内容
公告标题、正文和镜像帮助文档只维护一份中文,所有界面语言展示相同内容,正文节点标记 `lang="zh-CN"`。镜像介绍和可编辑站点文案仍按语言保存于内容数据中,不写入前端语言包。
## 建议技术架构
Vue、TypeScript、Vite 和 vue-i18n 已确定;以下后台组件与部署方式作为当前推荐方案,实施时结合服务器现状确认。
| 部分 | 技术建议 | 用途 |
| --- | --- | --- |
| 公共网站 | Vue 3 + TypeScript + Vite | 镜像列表、内容页面和局部动效 |
| 管理后台 | Vue 3 + Naive UI | 表格、配置表单、编辑与管理操作 |
| 国际化 | vue-i18n + Intl | 文案、数字、日期和相对时间 |
| 管理服务 | Go + Gin | 内容管理、权限、tunasync 适配和配置发布 |
| 业务存储 | SQLite | 公告、帮助、站点配置、账号和操作记录 |
| 文件与入口服务 | Nginx | 静态前端、镜像文件、目录浏览和 API 反向代理 |
| 同步引擎 | tunasync Manager / Worker | 镜像同步、任务控制和状态上报 |
| 进程管理 | systemd | 服务启动、日志及重启管理 |
```mermaid
flowchart LR
U[访客 / 管理员] --> N[Nginx]
N --> W[公共前台 / 管理后台]
N --> F[镜像目录与文件]
N --> A[MirrorOUC 管理服务]
A --> D[(业务数据库)]
A --> T[tunasync Manager]
T --> K[tunasync Worker]
K --> F
```
镜像文件由 Nginx 直接提供,支持包管理器访问与断点续传。网站路由、业务 API 和镜像路径需明确划分,前端路由回退不能拦截镜像文件请求或将不存在的文件返回为首页。
管理服务使用独立业务数据库,不直接修改 tunasync 的内部数据库。tunasync 管理接口仅通过本机或内部网络访问,由管理服务完成鉴权、权限检查和操作记录。
应用使用专用低权限账号运行。需要写入同步配置时,仅授权指定配置目录和必要操作;SSH 密钥、访问凭据和私有部署信息不写入仓库。
## tunasync 对接
### 状态与任务控制
上游当前提供 `/jobs`、Worker 查询和 `/cmd` 等接口,并支持配置重载。实施前需要核对服务器实际安装版本,建立统一适配层,将上游状态转换为前端使用的数据结构。
管理服务集中采集并缓存同步状态,前端初期采用约 15 秒一次的轮询。采集失败时保留最近一次有效数据并显示更新时间,避免将连接故障误显示为所有镜像同步失败。
任务操作需要区分“指令已提交”与“任务实际执行结果”,通过后续状态确认执行情况。日志查看与长期同步历史需要另外采集和保存,并设置保留期限。
### 配置发布
可视化配置编辑通过以下流程应用到 Worker:
```text
编辑草稿 → 校验 → 查看差异 → 保存版本 → 应用并重载 → 检查结果
↓
失败时支持回滚
```
配置应区分草稿、已应用版本和实际运行结果。发布时采用备份与原子替换,并检测文件是否已被其他操作修改,防止覆盖服务器上的人工变更。具体配置写入与重载方式需结合现有部署确认。
### 调度边界
tunasync 的原生 `interval` 表示同步完成后等待指定分钟数再执行,不等同于固定时刻调度。
首版建议优先支持原生间隔调度。如果需要“每天凌晨两点”或“仅夜间同步”,需要补充独立的调度逻辑,处理时区、并发、重复触发和失败重试,并确保每个任务只有一个调度来源。
固定时刻调度是否进入首版,尚待确定。
## 开发计划
### 第一阶段:基础工程与界面原型
- 初始化 Vue、TypeScript、Vite、路由和国际化结构。
- 建立亮暗主题变量及基础组件。
- 完成首页、搜索筛选、移动端布局和同步信息滚动动效。
- 使用明确标识的演示数据覆盖正常、同步中、失败、暂停和未知状态。
- 检查中英文布局、键盘操作和减少动态效果模式。
### 第二阶段:真实数据与内容管理
- 核对服务器环境、tunasync 版本和现有配置。
- 建立管理服务与状态适配层,接入真实镜像列表。
- 完成公告、帮助、常用下载和站点设置。
- 完成后台登录、内容编辑;公告和镜像帮助统一中文,其他站点文案按需支持多语言。
- 配置镜像文件服务、网站路由与部署流程。
### 第三阶段:运维管理
- 完成可视化同步配置、配置版本与发布流程。
- 完成任务操作、结果确认、日志及同步历史。
- 实现确认纳入范围的调度策略。
- 验证配置错误、重载失败、状态断连及回滚场景。
## 验证重点
- 切换语言后,公开网站与后台均无遗漏的界面文案,语言键和参数完整。
- 长英文、长镜像名、窄屏以及亮暗主题下均能正常阅读和操作。
- 状态刷新不打断搜索、点击和键盘焦点,减少动态效果设置生效。
- 状态过期、无数据和同步失败能够正确区分。
- Markdown 内容渲染、管理权限与配置发布经过针对性验证。
- 镜像文件链接、错误码和断点续传行为符合实际下载需求。
## 仓库与素材
根目录 `素材/` 已通过 `.gitignore` 忽略,原始素材不提交到 Git。实际使用的发布资源应按需整理到应用资源目录,避免整体复制原始素材文件夹。
前端预览已实现,依赖版本、开发命令、构建及校验方式见 [README.md](README.md)。当前数据均为演示数据;真实接口、服务配置和部署文档将在后端接入阶段补充。
## 待明确事项
- 首版是否需要固定时刻或指定时间窗口的同步调度。
- 服务器现有服务、目录结构、tunasync 版本及配置管理方式。
- 正式访问域名、可用线路和首批镜像范围。
- 网站标识、联系方式、友链及首批帮助文档内容。
## 参考资料
- [tunasync 项目](https://github.com/tuna/tunasync)
- [tunasync Worker 配置说明](https://github.com/tuna/tunasync/blob/master/docs/zh_CN/configs.md)
- [tunasync 配置重载与操作说明](https://github.com/tuna/tunasync/blob/master/docs/zh_CN/tips.md)
- [吉林大学开源镜像站](https://mirrors.jlu.edu.cn/)
- [清华大学开源软件镜像站](https://mirrors.tuna.tsinghua.edu.cn/)
- [中国科学技术大学开源软件镜像](https://mirrors.ustc.edu.cn/)
参考站用于研究功能和信息布局,MirrorOUC 的视觉与交互围绕中国海洋大学品牌单独设计。
+1 -1
View File
@@ -1,6 +1,6 @@
:root {
--muted: var(--ink-2);
/* Palette from itouc.cn; source values and component mapping are in DESIGN.md. */
/* Palette from itouc.cn. */
--blue: #0969da; --blue-bright: #58a6ff; --blue-soft: rgba(9, 105, 218, .08);
--ink: #24292f; --ink-2: #343a40; --ink-3: var(--ink-2); --line: #d0d7de; --line-soft: #d8dee4;
--paper: #fff; --surface: #f6f8fa; --panel: #fff; --panel-blue: var(--surface);