mainPage · 作品集主页

Zikai 的作品集主页 -- Vue 3 模块化多项目展示站。浅色极简、中英双语（英文按需懒加载）。每个项目页签是一个独立「模块」，由注册表自动生成页签与路由 -- 新增/删除页签只增删一个文件夹，互不影响。

架构细节、新增页签指南、子项目管理见 docs/。

项目结构

mainPage/
├── index.html
├── package.json                  # vue / vue-i18n / vue-router
├── vite.config.js                # 构建输出到 dist/，再由 npm run deploy rsync 到 /var/www/html
├── deploy.sh                     # 整体部署：构建 + rsync + Apache 反代 + 重启 zTools2
├── .gitmodules                   # git submodule：timeTableFix / z449 / zPDF_package / zWhiteBoard
├── README.md
├── docs/                         # 架构 / 新增页签 / 子模块管理 / 部署文档
├── public/favicon.svg
├── third_party/                  # ★ git submodule 子项目
│   ├── timeTableFix/             #   ICS 日程整理器（纯前端）
│   ├── z449/                     #   移动游戏项目展示页（纯前端）
│   ├── zPDF_package/             #   PDF 转换前端（同源调用 zTools2 /api/pdf/*）
│   └── zWhiteBoard/              #   共享记事本前端（同源调用 zTools2 /api/wb/* + /api/ws/wb/*）
└── src/
    ├── main.js                   # 应用入口（挂载 i18n / router / 全局样式）
    ├── App.vue                   # 根布局：顶栏 + 标签导航 + <KeepAlive router-view> + 页脚
    ├── config/app.config.js      # 集中配置：各服务的同源探针路径（/api/health）与默认参数
    ├── i18n/                     # 国际化（中文同步注入；英文动态 import() 懒加载）
    ├── router/index.js           # 路由表由模块注册表自动生成
    ├── modules/                  # ★ 扩展点：每个页签一个文件夹
    │   ├── index.js              #   注册表（import.meta.glob 约定式收集，带容错）
    │   ├── mobile-game/          #   移动游戏页签（包装 z449 子模块）
    │   ├── whiteboard/           #   共享记事本页签（包装 zWhiteBoard 子模块 + 存活校验）
    │   ├── timetable/            #   日程整理页签（包装 timeTableFix 子模块）
    │   ├── pdf/                  #   PDF 转换页签（包装 zPDF_package 子模块 + 存活校验）
    │   └── calendar/             #   隐藏页（仅手动访问 /cqy）
    ├── components/               # 共享组件（TabNav / LanguageSwitcher / ui 基元含 PageShell）
    ├── composables/              # useProjects / useLiveness / useI18nLazy / useLocale
    └── styles/                   # variables.css（主题令牌）+ base.css

外部依赖

项	要求
Node.js	≥ 18
Web 服务器	Apache 2.4（启用 mod_rewrite / mod_proxy / mod_proxy_wstunnel），对外静态服务构建产物
SPA 回退	history 模式需站点根 .htaccess 回退到 index.html
后端	zTools2（127.0.0.1:6867），由 Apache 反代 /api/；PDF/白板页签依赖其 REST API 与 WebSocket

四个子模块均为构建期组件集成（非 iframe），共享 mainPage 的构建与 KeepAlive 缓存。各子模块依赖在其自身 node_modules，由各自 package.json 管理。

如何使用

# 1. 安装 Node.js 18
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo bash -
sudo apt-get install -y nodejs

# 2. 取代码（含四个子模块）
git clone --recursive https://git.zikai.wang/zikai/zMainPage.git mainPage
cd mainPage
# 若已 clone 但未带子模块：git submodule update --init --recursive
npm install
# 子模块需各自安装依赖（构建期编译其 .vue）
(cd third_party/timeTableFix && npm install)
(cd third_party/z449 && npm install)
(cd third_party/zPDF_package && npm install)
(cd third_party/zWhiteBoard && npm install)

# 3. 构建到 dist/（再由 npm run deploy rsync 同步到 /var/www/html）
npm run build

# 4. 安装并启用 Apache
sudo apt-get install -y apache2
sudo a2enmod rewrite proxy proxy_http proxy_wstunnel headers

站点根放 .htaccess（Apache 需 AllowOverride All）做 SPA 回退：

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^ - [L]
RewriteRule ^ index.html [L]

并把 /var/www/html 设为 DocumentRoot。后端 zTools2 需监听 127.0.0.1:6867，并在 vhost 加反代规则（见下方 Apache 配置）。整体部署可用 ./deploy.sh 一键完成（详见 docs/deployment.md）。

Apache 反代 zTools2（/api/ -> 127.0.0.1:6867）

<VirtualHost *:80>
    DocumentRoot /var/www/html
    ProxyPreserveHost On
    # 所有 zTools2 入口（API/静态/探针/WS）统一在 /api/ 下，一条规则即可
    ProxyPass        /api/   http://127.0.0.1:6867/api/
    ProxyPassReverse /api/   http://127.0.0.1:6867/api/
    <Directory /var/www/html>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

WebSocket 走 /api/ws/wb/{id}，需 a2enmod proxy_wstunnel 以透传 Upgrade 头。

开发命令

npm install      # 首次安装依赖
npm run dev      # 开发服务器 http://localhost:5173
npm run build    # 构建到 dist/
npm run deploy   # 构建并 rsync 同步到 /var/www/html
npm run preview  # 本地预览构建产物

了解更多

• 架构（模块注册 / PageShell / KeepAlive / 存活校验）
• 如何新增一个项目页签
• 子项目 timeTableFix 管理（submodule 升级 / 移除）
• 子项目 z449 管理（submodule + i18n prop 桥接）
• 子项目 zPDF_package 管理（submodule + 同源 API 集成）
• 子项目 zWhiteBoard 管理（submodule + 同源 API/WS 集成）
• 部署指南（组件独立 / 整体 / 持久化 systemd）
• README 勘误记录