🌐 操作文档

文档站部署

把本套 Graduate OS Docs 作为纯静态站部署到宝塔

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. 推荐域名与目录#

示例：

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

文档站目录建议：

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

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

2. DNS 解析#

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

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

如果你的实际子域名是：

docs.2fa.aastudy.com

就按对应域名配置。

等待解析生效。

3. 宝塔添加网站#

进入：

宝塔 → 网站 → 添加站点

填写：

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

保存。

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

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

4. 上传文档站 ZIP#

进入：

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

上传：

Graduate-OS-Docs-Site-20260828.zip

点击：

解压

解压到当前目录。

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

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/

错误：

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

正确：

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

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

5. 默认首页#

宝塔：

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

确认：

index.html

排在前面即可。

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

6. 申请 SSL#

进入：

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

选择域名并申请证书。

成功后开启：

强制 HTTPS

浏览器打开：

https://docs.xjtu.example.com

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

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

宝塔站点配置中通常有：

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

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

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

#error_page 404/404.html;

如果保存配置时出现：

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

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

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

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

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

进入：

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

不要替换整份配置。

在正常自定义区域增加：

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

修改后先：

/www/server/nginx/sbin/nginx -t

通过再重载 Nginx。

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

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

宝塔文件：

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

里面可以修改：

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

例如：

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

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

保存后：

Ctrl + F5

强制刷新浏览器。

10. 修改 Logo#

替换：

/assets/brand-logo.svg

建议：

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

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

11. 修改 Favicon#

替换：

/assets/favicon.svg

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

Ctrl + F5

或者使用无痕窗口测试。

12. 文档站功能测试#

打开首页后依次检查：

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

13. 文档站如何更新#

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

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

因为是纯静态站：

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

14. 如何自己编辑内容#

发布包中保留：

/markdown/

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

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

源码包还包含：

build.py

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

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

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

15. 安全注意事项#

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

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

示例必须使用：

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

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

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

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

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

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

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

17. 故障排查#

打开域名是宝塔默认页#

确认网站根目录是否是：

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

并确认里面有：

index.html

404#

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

CSS 全没了#

确认：

/assets/styles.css

存在，并且浏览器访问：

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

能够打开。

搜索没有结果#

确认：

/assets/search-index.json

存在。

修改颜色后不生效#

浏览器：

Ctrl + F5

并检查：

/assets/brand-config.js

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

SSL 申请失败#

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

/.well-known/acme-challenge/

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

18. 最终目录关系#

19. 最终验收#

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

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