# Graduate OS Docs 文档站 · 宝塔部署与配置指南

> 对应源码包：`Graduate-OS-Docs-Site-20260828.zip`  
> 类型：纯静态文档站  
> 推荐环境：Ubuntu 22.04 + 宝塔 Linux + Nginx  
> 不需要：MySQL、PHP、Node.js、PM2、Docker

这个文档站和 Graduate OS 主站是两个独立网站。主站继续运行在 `127.0.0.1:3000`；文档站只由 Nginx 直接读取 HTML/CSS/JS 文件，因此部署非常轻。

---

# 1. 推荐域名与目录

示例：

```text
主站：https://xjtu.example.com
文档：https://docs.xjtu.example.com
```

文档站目录建议：

```text
/www/wwwroot/docs.xjtu.example.com
```

把示例域名换成你自己的域名。

---

# 2. DNS 解析

在域名服务商新增 A 记录：

```text
主机记录：docs.xjtu
记录类型：A
记录值：你的服务器公网 IPv4
```

如果你的实际子域名是：

```text
docs.2fa.aastudy.com
```

就按对应域名配置。

等待解析生效。

---

# 3. 宝塔添加网站

进入：

```text
宝塔 → 网站 → 添加站点
```

填写：

```text
域名：docs.xjtu.example.com
根目录：/www/wwwroot/docs.xjtu.example.com
PHP版本：纯静态
数据库：不创建
FTP：不创建
```

保存。

**这个文档站不需要反向代理。**

不要把它反代到 Graduate OS 的 `3000` 端口。

---

# 4. 上传文档站 ZIP

进入：

```text
宝塔 → 文件 → /www/wwwroot/docs.xjtu.example.com
```

上传：

```text
Graduate-OS-Docs-Site-20260828.zip
```

点击：

```text
解压
```

解压到当前目录。

解压后项目根目录必须直接看到：

```text
index.html
assets/
getting-started/
server-baota/
install/
env-security/
nginx-pm2/
ai-provider/
serpapi-radar/
papers-ai/
jobs-interviews/
question-bank/
maintenance/
troubleshooting/
checklist/
downloads/
```

错误：

```text
/www/wwwroot/docs.xjtu.example.com/Graduate-OS-Docs-Site/index.html
```

正确：

```text
/www/wwwroot/docs.xjtu.example.com/index.html
```

如果多套了一层目录，用宝塔文件管理器把里面的文件全部移动到站点根目录。

---

# 5. 默认首页

宝塔：

```text
网站 → docs.xjtu.example.com → 设置 → 默认文档
```

确认：

```text
index.html
```

排在前面即可。

普通宝塔 Nginx 默认配置通常不需要其他修改。

---

# 6. 申请 SSL

进入：

```text
网站 → docs.xjtu.example.com → 设置 → SSL → Let's Encrypt
```

选择域名并申请证书。

成功后开启：

```text
强制 HTTPS
```

浏览器打开：

```text
https://docs.xjtu.example.com
```

应该直接进入 Graduate OS Docs 首页。

---

# 7. 不要破坏宝塔 SSL 保护区

宝塔站点配置中通常有：

```text
#CERT-APPLY-CHECK--START
...
#CERT-APPLY-CHECK--END

#SSL-START
#error_page 404/404.html;
...
#SSL-END
```

不要修改宝塔要求保留的：

```text
#error_page 404/404.html;
```

如果保存配置时出现：

```text
请勿修改SSL相关配置中注释的404规则
```

说明你改到了受保护的 SSL 区域。恢复该行即可。

**本静态文档站默认不需要你修改 Nginx 配置，所以最安全的做法就是保持宝塔自动生成配置。**

---

# 8. 可选：添加静态文件缓存

只有你明确需要时再加；不加也能正常使用。

进入：

```text
网站 → docs.xjtu.example.com → 设置 → 配置文件
```

不要替换整份配置。

在正常自定义区域增加：

```nginx
location ~* \.(css|js|svg|png|jpg|jpeg|webp|ico)$ {
    expires 7d;
    add_header Cache-Control "public, max-age=604800";
}
```

修改后先：

```bash
/www/server/nginx/sbin/nginx -t
```

通过再重载 Nginx。

如果你不熟悉 Nginx，**这一项直接跳过。**

---

# 9. 修改网站名称与颜色

宝塔文件：

```text
/www/wwwroot/docs.xjtu.example.com/assets/brand-config.js
```

里面可以修改：

```text
网站名称
副标题
版本号
主色
辅助色
强调色
Footer
```

例如：

```javascript
window.DOCS_BRAND = {
  name: "Graduate OS Docs",
  subtitle: "Research · AI · Career",
  version: "Final 2026.08",
  primary: "#6f7edb",
  secondary: "#57b6a8",
  accent: "#e99a8d"
};
```

当前默认就是低饱和、清晰、但比纯灰页面更鲜活的设计。

保存后：

```text
Ctrl + F5
```

强制刷新浏览器。

---

# 10. 修改 Logo

替换：

```text
/assets/brand-logo.svg
```

建议：

```text
正方形或横向 SVG
背景透明
不要放真实密钥、账号等信息
```

如果不想自己设计，保留默认 Graduate OS 图标即可。

---

# 11. 修改 Favicon

替换：

```text
/assets/favicon.svg
```

浏览器可能缓存 favicon，替换后建议：

```text
Ctrl + F5
```

或者使用无痕窗口测试。

---

# 12. 文档站功能测试

打开首页后依次检查：

- [ ] 左侧导航正常
- [ ] 手机端菜单按钮正常
- [ ] `Ctrl + K` 可以打开搜索
- [ ] 搜索 “SECRET_ENCRYPTION_KEY” 能定位配置说明
- [ ] 搜索 “524” 能定位 AI 超时故障排查
- [ ] 搜索 “Paper Radar” 能定位 Radar 使用说明
- [ ] 代码块右上角复制按钮正常
- [ ] 深色模式按钮正常
- [ ] 页面右侧目录正常
- [ ] 上一篇 / 下一篇跳转正常
- [ ] Markdown 下载链接正常

---

# 13. 文档站如何更新

以后如果得到新版文档站 ZIP：

```text
宝塔 → 文件 → 文档站目录
→ 上传新版 ZIP
→ 解压覆盖
→ Ctrl + F5
```

因为是纯静态站：

```text
不需要 npm ci
不需要 build
不需要 Prisma
不需要 PM2 restart
不需要数据库 migration
```

---

# 14. 如何自己编辑内容

发布包中保留：

```text
/markdown/
```

里面是各页面对应的 Markdown 源文档。

日常如果只是改一个小错误，直接编辑对应生成的 HTML 也可以；长期维护更推荐修改 Markdown 后重新生成站点。

源码包还包含：

```text
build.py
```

这是可选的静态生成脚本，不影响已经生成好的站点运行。

在本地有 Python + Mistune 环境时可以重新生成全部 HTML。

普通服务器部署**不需要运行 `build.py`**。

---

# 15. 安全注意事项

这个技术文档站可以公开，但不要在文档中写入：

```text
真实 .env
真实数据库密码
真实 API Key
SECRET_ENCRYPTION_KEY 真值
SESSION_SECRET 真值
宝塔账号密码
服务器 SSH 密码
Basic Auth 密码
```

示例必须使用：

```text
CHANGE_ME
sk-你的Key
你的数据库密码
你的域名
```

不要上传 Graduate OS 主站的 `storage/papers` 到文档站。

---

# 16. 如果想让文档站也加密码

如果你不想公开技术文档，可以使用宝塔：

```text
网站 → 访问限制 → 密码访问
```

创建单独的文档站用户名和密码。

不要和 Graduate OS 主站管理员密码共用。

---

# 17. 故障排查

## 打开域名是宝塔默认页

确认网站根目录是否是：

```text
/www/wwwroot/docs.xjtu.example.com
```

并确认里面有：

```text
index.html
```

## 404

检查是否多套了一层目录。

## CSS 全没了

确认：

```text
/assets/styles.css
```

存在，并且浏览器访问：

```text
https://docs.xjtu.example.com/assets/styles.css
```

能够打开。

## 搜索没有结果

确认：

```text
/assets/search-index.json
```

存在。

## 修改颜色后不生效

浏览器：

```text
Ctrl + F5
```

并检查：

```text
/assets/brand-config.js
```

语法是否被误删括号或逗号。

## SSL 申请失败

先不要加 Basic Auth / IP 白名单，确保：

```text
/.well-known/acme-challenge/
```

可以正常由宝塔验证；SSL 成功后再添加额外限制。

---

# 18. 最终目录关系

推荐：

```text
/www/wwwroot/
├── graduate-os/                 # Graduate OS 主站源码
│   ├── .env                     # 绝不公开
│   ├── storage/papers/          # 私有 PDF
│   └── ...
│
└── docs.xjtu.example.com/       # 文档静态站
    ├── index.html
    ├── assets/
    ├── getting-started/
    ├── install/
    ├── troubleshooting/
    └── ...
```

两个站点彼此独立，文档站故障不会影响 Graduate OS 主站。

---

# 19. 最终验收

- [ ] DNS 已解析
- [ ] 宝塔静态站创建成功
- [ ] ZIP 解压到正确根目录
- [ ] `index.html` 正常
- [ ] SSL 正常
- [ ] 强制 HTTPS 正常
- [ ] Logo / Favicon 正常
- [ ] 搜索正常
- [ ] 深色模式正常
- [ ] 代码复制正常
- [ ] 各章节链接正常
- [ ] 下载 Markdown 正常
- [ ] 文档中没有任何真实密码或 API Key

全部通过后，Graduate OS Docs 文档站就可以长期使用。