一种静态网页部署平台
- 项目介绍
- 26天前
- 51热度
- 0评论
项目概览
更好的呈现效果请通过 丽姐的静态页面部署平台访问 一种静态网页部署平台
- 基于 Vue 3 + Vite 的静态页面索引前端，展示
data/pages.json中的页面卡片，可搜索、排序、编辑、删除与触发重建。 - 基于 Express + Multer 的上传服务（
scripts/upload-server.mjs），提供上传/本地登记/删除/编辑/重建等接口，支持密码鉴权与 Docker 内构建。 - Docker 多服务：
builder负责前端打包并同步到宿主静态目录；upload提供上传 API 并可在容器内触发builder。 - AI 摘要：前端可调用 OpenAI 兼容接口生成摘要（需配置
VITE_OPENAI_API_KEY等）。
目录与角色
关键目录速览
| 路径 | 职责 |
|---|---|
src/ |
前端页面与组件（App.vue、PageCard.vue、EditModal.vue、AuthModal.vue） |
scripts/upload-server.mjs |
Express 上传/删除/编辑/重建 API，写入 data/pages.json、public/data/pages.json，并可触发 Docker 构建 |
scripts/rebuild.sh |
简化的手动构建脚本，调用 docker compose builder |
data/pages.json |
线上/本地共用的页面索引源，构建时同步到 public/data/pages.json 与宿主静态目录 |
docker-compose.yml |
定义 builder 与 upload 服务的挂载、端口、环境变量 |
Dockerfile |
multi-stage：基础镜像 -> 依赖层 -> upload 运行层 |
前端特性
- 列表：从
/data/pages.json拉取，支持搜索（标题/描述）、按时间或标题排序。 - 上传：表单 + 密码弹窗，POST
/api/upload，字段包含 slug/title/description/image 与 HTML 文件。 - 编辑：弹窗内可改标题/摘要/首图，POST
/api/edit。 - 删除：确认弹窗，POST
/api/delete。 - 构建：手动按钮 POST
/api/rebuild，后端可跳过构建（SKIP_BUILD=1）。 - 主题：浅色 / 深色 / 自动，保存在 localStorage，应用到
:root[data-theme]。 - AI 摘要：点击“AI 生成摘要”会抓取页面正文文本，调用 OpenAI Chat Completions 生成描述，支持语言切换（auto/zh/en）。
后端（upload server）概述
- 框架：Express + Multer，
basic-auth支持 Header/Basic 两种密码传递，校验x-upload-token或 Basic auth 密码。 - 文件落盘：目标目录由
PAGES_DIR（默认宿主静态根）决定，文件名基于 slug 归一化；如冲突自动追加计数后缀。 - 数据写入：
writePagesJson同步到项目内data/pages.json、public/data/pages.json，并尝试写宿主静态目录data/pages.json。 - 构建触发：
/api/rebuild调用docker compose run --rm builder，可通过SKIP_BUILD跳过。 - 本地登记：
/api/upload-local支持先 scp 再登记的模式（不经 HTTP 上传）。
接口与数据约定
API 列表
| 方法 | 路径 | 功能 | 认证 |
|---|---|---|---|
| POST | /api/upload |
上传 HTML，写入 pages.json | x-upload-token 或 Basic 密码 |
| POST | /api/upload-local |
已有 HTML（scp）登记到 pages.json | 同上 |
| POST | /api/delete |
删除 HTML + 从 pages.json 移除 | 同上 |
| POST | /api/edit |
更新标题/描述/首图 | 同上 |
| POST | /api/rebuild |
触发 builder 构建 | 同上 |
| GET | /api/health |
健康检查 | 无 |
pages.json 结构
| 字段 | 说明 |
|---|---|
url |
线上可访问的完整 URL |
title |
卡片标题 |
description |
摘要文本（AI 或人工） |
image |
首图 URL，可为空 |
created_at |
ISO 时间戳，按此排序 |
环境变量
运行时环境变量速查
| 变量 | 默认值 | 作用 |
|---|---|---|
UPLOAD_PASSWORD |
change-me |
上传、编辑、删除、重建的鉴权密码 |
UPLOAD_PORT |
8787 |
upload 服务监听端口 |
HOST_STATIC_ROOT |
/WWW_ROOT/static |
宿主静态根目录（builder rsync 目标） |
PAGES_DIR |
同上 | HTML 写入目录；默认落在静态根，方便直接以根路径访问 |
BASE_URL |
https://pages.lijie.space/ |
生成页面 URL 的基准 |
HOST_PROJECT_ROOT |
/root/Static-Page-Server |
宿主仓库路径，触发 docker compose 的工作目录 |
SKIP_BUILD |
空 | 1/true/yes 时跳过自动构建 |
VITE_OPENAI_API_KEY |
空 | 前端 AI 摘要所需 Key（浏览器侧调用，注意暴露风险） |
VITE_OPENAI_BASE_URL |
https://api.openai.com/v1 |
OpenAI 兼容端点 |
VITE_OPENAI_MODEL |
gpt-4o-mini |
Chat 模型名 |
开发与运行
本地开发启动
pnpm install
pnpm dev
- Vite 开发服务器运行在
5173，已配置/api代理到http://localhost:8787。 - 需同时启动上传服务：
启动上传服务
pnpm upload:serve
Docker 一键构建/服务（推荐与线上一致）
# 构建并同步静态资源到宿主静态目录
HOST_STATIC_ROOT=/WWW_ROOT/static docker compose run --rm builder
# 启动上传服务（含 API）
UPLOAD_PASSWORD=change-me docker compose up upload
构建与发布流
1) 前端从 data/pages.json 读取卡片；上传/编辑/删除都会同步三份 pages.json（仓库、public、宿主静态目录）。
2) 触发 /api/rebuild 或执行 docker compose run builder：
- 安装依赖 → pnpm build → 将 dist/index.html、dist/assets/**、dist/data/** rsync 到宿主静态目录（默认 /WWW_ROOT/static）。
3) 访问：若 HTML 直接放在静态根，URL 为 BASE_URL + filename；若设定 pages 子目录，URL 为 BASE_URL/pages/<filename>。
AI 摘要功能
- 入口：编辑弹窗的“AI 生成摘要”。
- 流程：抓取目标 URL → DOMParser 提取正文文本（截断 6000 字符）→ 调用 Chat Completions → 回填描述。
- 语言：
auto会按正文语言自适应；可手动切换zh/en。 - 安全提示：Key 暴露在前端，若需安全调用，可改为后端代理。
安全与最佳实践
- 必须设置强密码：
UPLOAD_PASSWORD，并通过 HTTPS 访问上传端点。 - 可将上传服务置于内网，仅前端静态站点暴露外网。
- 本地/CI 构建可设置
SKIP_BUILD=1跳过 docker，提升迭代速度。 - 文件名归一化：slug 中非
[A-Za-z0-9._-]会被替换为-，并保证.html后缀；冲突时自动追加-1/-2...。
常见操作备忘
- 添加页面（HTTP 上传）：填写 slug/title/description/image，上传 HTML → 输入密码 → 成功后刷新列表 → 如需同步线上，点击“手动构建”。
- 添加页面（scp + 登记）：将 HTML 放入
PAGES_DIR→ POST/api/upload-local携带 slug/title/description/image → 手动构建。 - 修改元数据：在卡片点击编辑，或调用
/api/edit。 - 删除页面：卡片删除或
/api/delete，操作不可恢复。