dekun
c9f78ef25f
VitePress did not auto-inject SW registration; manual registerSW enables true app install on HTTPS. Co-authored-by: Cursor <cursoragent@cursor.com>
458 lines
10 KiB
Markdown
458 lines
10 KiB
Markdown
# DAO DE JING 部署文档
|
||
|
||
本文档说明如何在 **Ubuntu 本地** 部署站点，并通过 **NPS TCP 内网穿透** + **云服务器反向代理** 对外提供访问。
|
||
|
||
---
|
||
|
||
## 1. 架构说明
|
||
|
||
```
|
||
用户浏览器
|
||
↓
|
||
云服务器（Nginx / 宝塔反代，HTTPS）
|
||
↓
|
||
NPS 服务端（TCP 转发）
|
||
↓
|
||
NPS 客户端（内网 Ubuntu）
|
||
↓
|
||
Express 登录服务（0.0.0.0:12100）
|
||
↓
|
||
VitePress 静态站点（.vitepress/dist）
|
||
```
|
||
|
||
| 组件 | 作用 |
|
||
|------|------|
|
||
| **VitePress** | 将 Markdown 文档构建为静态 HTML |
|
||
| **Express** | 提供登录校验，保护全部页面 |
|
||
| **NPS TCP** | 将内网 `12100` 端口映射到公网 |
|
||
| **云服务器反代** | 绑定域名、HTTPS（由你自行配置） |
|
||
|
||
> 登录鉴权在 **本地 Express 层** 完成，不依赖宝塔或 Nginx 的访问限制。
|
||
|
||
---
|
||
|
||
## 2. 环境要求
|
||
|
||
| 项目 | 要求 |
|
||
|------|------|
|
||
| 操作系统 | Ubuntu 20.04+（或其他 Linux） |
|
||
| Node.js | **18.x 或 20.x**（推荐 LTS） |
|
||
| npm | 9+ |
|
||
| Git LFS | 可选，用于拉取图片资源 |
|
||
| 端口 | **12100**（Express 服务端口） |
|
||
|
||
### 2.1 安装 Node.js（Ubuntu 示例）
|
||
|
||
```bash
|
||
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||
sudo apt-get install -y nodejs
|
||
node -v
|
||
npm -v
|
||
```
|
||
|
||
### 2.2 安装 Git LFS（可选，建议）
|
||
|
||
仓库中部分图片使用 Git LFS 存储，部署前建议执行：
|
||
|
||
```bash
|
||
sudo apt-get install -y git-lfs
|
||
git lfs install
|
||
git lfs pull
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 获取代码
|
||
|
||
```bash
|
||
git clone https://git.bz121.com/dekun/DAO_DE_JING.git
|
||
cd DAO_DE_JING
|
||
git lfs pull # 可选
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 安装与构建
|
||
|
||
```bash
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
构建完成后，静态文件输出到 `.vitepress/dist/`。
|
||
|
||
### 常用命令
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `npm run build` | 仅构建静态站点 |
|
||
| `npm run start` | 启动服务（需先 build） |
|
||
| `npm run serve` | **构建 + 启动**（推荐一键部署） |
|
||
| `npm run docs:dev` | 开发模式，端口 5173，**无登录** |
|
||
|
||
---
|
||
|
||
## 5. 登录配置
|
||
|
||
首次启动时，若不存在 `server/auth.config.json`，会自动从示例文件复制生成。
|
||
|
||
```bash
|
||
cp server/auth.config.example.json server/auth.config.json
|
||
```
|
||
|
||
编辑 `server/auth.config.json`：
|
||
|
||
```json
|
||
{
|
||
"username": "你的用户名",
|
||
"password": "你的强密码",
|
||
"sessionSecret": "随机长字符串，至少32位"
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `username` | 登录用户名 |
|
||
| `password` | 登录密码（明文存储，仅用于本地校验） |
|
||
| `sessionSecret` | Session 签名密钥，务必修改为随机字符串 |
|
||
|
||
> 该文件已加入 `.gitignore`，**不会提交到 Git**。请勿修改 `.env.production`。
|
||
|
||
修改配置后需重启服务：
|
||
|
||
```bash
|
||
npm run start
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 启动本地服务
|
||
|
||
```bash
|
||
npm run serve
|
||
```
|
||
|
||
启动成功后输出：
|
||
|
||
```
|
||
DAO DE JING 站点已启动: http://0.0.0.0:12100
|
||
登录页: /login
|
||
```
|
||
|
||
### 本地验证
|
||
|
||
```bash
|
||
curl -I http://127.0.0.1:12100/
|
||
# 应返回 302，跳转到 /login
|
||
|
||
curl -I http://127.0.0.1:12100/login
|
||
# 应返回 200
|
||
```
|
||
|
||
浏览器访问 `http://<内网IP>:12100/login`，使用配置的账号密码登录。
|
||
|
||
---
|
||
|
||
## 7. NPS TCP 内网穿透
|
||
|
||
在内网 Ubuntu 上运行 NPS 客户端，将本地 **12100** 以 **TCP 模式** 映射到 NPS 服务端。
|
||
|
||
### 客户端配置示例（nps.conf）
|
||
|
||
```ini
|
||
[common]
|
||
server_addr=<NPS服务端IP>
|
||
server_port=<NPS服务端端口>
|
||
vkey=<你的密钥>
|
||
|
||
[tcp-12100]
|
||
mode=tcp
|
||
target_addr=127.0.0.1:12100
|
||
server_port=<公网映射端口>
|
||
```
|
||
|
||
映射完成后，云服务器可通过 `127.0.0.1:<公网映射端口>` 访问内网站点。
|
||
|
||
### 注意事项
|
||
|
||
- 使用 **TCP 模式**，不要用 HTTP 模式（Express 自行处理 HTTP 与 Session）
|
||
- 确保 Ubuntu 防火墙放行出站连接
|
||
- 确保 `12100` 端口未被其他程序占用：
|
||
|
||
```bash
|
||
ss -tlnp | grep 12100
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 云服务器反向代理（参考）
|
||
|
||
在云服务器（宝塔 / Nginx）上，将域名反代到 NPS 映射端口。**无需在宝塔配置额外登录**。
|
||
|
||
### Nginx 反代示例
|
||
|
||
```nginx
|
||
server {
|
||
listen 443 ssl http2;
|
||
server_name your-domain.com;
|
||
|
||
# ssl_certificate ...;
|
||
# ssl_certificate_key ...;
|
||
|
||
location / {
|
||
proxy_pass http://127.0.0.1:<NPS映射端口>;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
}
|
||
}
|
||
```
|
||
|
||
Express 已启用 `trust proxy`，HTTPS 反代后 Session Cookie 可正常工作。
|
||
|
||
---
|
||
|
||
## 9. 后台常驻运行（systemd）
|
||
|
||
创建 systemd 服务，实现开机自启与崩溃重启。
|
||
|
||
```bash
|
||
sudo nano /etc/systemd/system/dao-de-jing.service
|
||
```
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=DAO DE JING Site
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=你的用户名
|
||
WorkingDirectory=/path/to/DAO_DE_JING
|
||
ExecStart=/usr/bin/npm run start
|
||
Restart=on-failure
|
||
RestartSec=5
|
||
Environment=NODE_ENV=production
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
```bash
|
||
# 首次需手动构建
|
||
cd /path/to/DAO_DE_JING
|
||
npm run build
|
||
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable dao-de-jing
|
||
sudo systemctl start dao-de-jing
|
||
sudo systemctl status dao-de-jing
|
||
```
|
||
|
||
查看日志：
|
||
|
||
```bash
|
||
journalctl -u dao-de-jing -f
|
||
```
|
||
|
||
> `ExecStart` 使用 `npm run start`（仅启动，不重新构建）。更新内容后需手动 `npm run build` 再 `systemctl restart dao-de-jing`。
|
||
|
||
---
|
||
|
||
## 10. 更新部署
|
||
|
||
文档内容有变更时：
|
||
|
||
```bash
|
||
cd DAO_DE_JING
|
||
git pull
|
||
git lfs pull # 如有图片更新
|
||
npm install # 依赖有变更时
|
||
npm run build
|
||
sudo systemctl restart dao-de-jing # 若使用 systemd
|
||
```
|
||
|
||
或一键：
|
||
|
||
```bash
|
||
npm run serve
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 目录结构（部署相关）
|
||
|
||
```
|
||
DAO_DE_JING/
|
||
├── .vitepress/
|
||
│ ├── config.mts # VitePress 配置
|
||
│ ├── dist/ # 构建产物（npm run build 生成）
|
||
│ └── public/ # 构建时自动同步 assets/images
|
||
├── server/
|
||
│ ├── index.js # Express 服务（端口 12100）
|
||
│ ├── auth.config.json # 登录配置（本地，不提交 Git）
|
||
│ ├── auth.config.example.json
|
||
│ └── public/login.html # 登录页
|
||
├── scripts/prepare-public.mjs
|
||
├── index.md # 站点首页
|
||
├── package.json
|
||
└── DEPLOY.md # 本文档
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 常见问题
|
||
|
||
### Q1：启动报错「未找到构建产物 .vitepress/dist」
|
||
|
||
先执行构建：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
### Q2：登录后刷新又跳回登录页
|
||
|
||
- 检查 `sessionSecret` 是否已修改且重启后保持一致
|
||
- 反代是否传递了 `X-Forwarded-Proto`（HTTPS 场景）
|
||
- 浏览器是否禁用了 Cookie
|
||
|
||
### Q3：图片不显示
|
||
|
||
执行 Git LFS 拉取：
|
||
|
||
```bash
|
||
git lfs pull
|
||
npm run build
|
||
```
|
||
|
||
部分章节引用的图片若仓库中不存在，页面可正常访问，仅图片为空。
|
||
|
||
### Q4：导航栏「五行 / 周易 / 中医」打开是 404
|
||
|
||
**必须重新构建**，`.vitepress/dist` 不会随 `git pull` 自动更新：
|
||
|
||
```bash
|
||
git pull
|
||
npm run build # 关键步骤，不可省略
|
||
npm run start # 或 systemctl restart dao-de-jing
|
||
```
|
||
|
||
构建完成后，目录下应存在例如 ` .vitepress/dist/周易/index.html`（不是只有 `README.html`）。
|
||
|
||
### Q5：端口被占用
|
||
|
||
```bash
|
||
ss -tlnp | grep 12100
|
||
# 结束占用进程或修改 server/index.js 中的 PORT 常量
|
||
```
|
||
|
||
### Q6：内网穿透后外网无法访问
|
||
|
||
1. 确认 Ubuntu 上 `npm run start` 正常运行
|
||
2. 确认 NPS 客户端在线，TCP 隧道状态正常
|
||
3. 确认云服务器反代指向正确的 NPS 映射端口
|
||
4. 确认云服务器安全组 / 防火墙已放行相应端口
|
||
|
||
---
|
||
|
||
## 13. 安装为应用（PWA）
|
||
|
||
站点已支持 **Progressive Web App**，可在手机和电脑上安装为独立应用。
|
||
|
||
### 前提
|
||
|
||
- **对外访问必须使用 HTTPS**（云服务器反代层配置 SSL）
|
||
- 内网 `http://192.168.x.x:12100` 仅适合调试，Android 通常不会弹出「安装应用」
|
||
|
||
### 只能「创建快捷方式」，没有「安装应用」？
|
||
|
||
常见两个原因：
|
||
|
||
**1. 用了 HTTP 内网地址（如 `http://192.168.x.x:12100`）**
|
||
|
||
| 访问方式 | 浏览器行为 |
|
||
|----------|------------|
|
||
| HTTP 内网 IP | 只能「创建快捷方式」，**不能**真正安装 PWA |
|
||
| **HTTPS 域名** | 可「安装应用 / 添加到主屏幕」 |
|
||
|
||
**2. Service Worker 未注册（已在最新代码修复）**
|
||
|
||
更新后按 F12 → **Application（应用）** → **Service Workers**，应看到 `/sw.js` 状态为 **activated**。
|
||
|
||
若仍是红色报错，执行：
|
||
|
||
```bash
|
||
git pull && npm install && npm run build && npm run start
|
||
```
|
||
|
||
然后 **Ctrl+Shift+R** 强刷，或删除旧快捷方式后重装。
|
||
|
||
### 电脑（Chrome / Edge）
|
||
|
||
1. 用 HTTPS 域名打开站点并登录
|
||
2. 地址栏右侧点击 **「安装」** 或菜单 → **「安装 DAO DE JING / 道德经」**
|
||
3. 也可点击页面右下角 **「安装应用」** 按钮（Android / 部分桌面浏览器）
|
||
|
||
### Android 手机
|
||
|
||
1. Chrome 打开 **HTTPS 域名** 并登录
|
||
2. 点击右下角 **「安装应用」**，或菜单 → **「添加到主屏幕 / 安装应用」**
|
||
|
||
### iPhone / iPad
|
||
|
||
1. 必须用 **Safari** 打开 HTTPS 域名并登录
|
||
2. 点击底部分享按钮 **□↑**
|
||
3. 选择 **「添加到主屏幕」**
|
||
4. 页面右下角也会提示上述步骤
|
||
|
||
### 更新后
|
||
|
||
安装的应用不会自动更新构建内容，服务端更新后：
|
||
|
||
```bash
|
||
git pull && npm install && npm run build && npm run start
|
||
```
|
||
|
||
用户重新打开应用即可加载新版本（Service Worker 会自动更新静态资源）。
|
||
|
||
---
|
||
|
||
## 14. 安全建议
|
||
|
||
1. **立即修改** `server/auth.config.json` 中的默认密码和 `sessionSecret`
|
||
2. 不要将 `server/auth.config.json` 提交到 Git 或分享给他人
|
||
3. 通过 HTTPS 对外提供服务（在云服务器反代层配置 SSL）
|
||
4. 定期更新依赖：`npm update`
|
||
5. 限制 NPS 映射端口的访问来源（如云服务器安全组仅允许必要 IP）
|
||
|
||
---
|
||
|
||
## 15. 快速部署清单
|
||
|
||
```bash
|
||
# 1. 环境
|
||
node -v && npm -v
|
||
|
||
# 2. 代码
|
||
git clone <repo> && cd DAO_DE_JING
|
||
git lfs pull
|
||
|
||
# 3. 依赖与构建
|
||
npm install
|
||
npm run build
|
||
|
||
# 4. 登录配置
|
||
cp server/auth.config.example.json server/auth.config.json
|
||
nano server/auth.config.json
|
||
|
||
# 5. 启动
|
||
npm run start
|
||
|
||
# 6. 配置 NPS TCP → 12100
|
||
# 7. 配置云服务器反代 → NPS 映射端口
|
||
# 8. 浏览器访问域名，登录后使用
|
||
```
|