Docusaurus本地运行与Nginx部署

核对日期：2026-05-18

1. 当前站点模型

当前文档网站使用 Docusaurus 3 搭建，项目目录为：

agent-docs-site/

它不是只发布单个目录，而是通过配置驱动的多文档源同步，把允许发布的 Markdown、MDX、PDF、DOCX 和图片资源同步到站点：

源文档或文档目录
  -> agent-docs-site/docs-sync.config.json
  -> agent-docs-site/scripts/sync-docs.mjs
  -> agent-docs-site/docs/
  -> Docusaurus build
  -> agent-docs-site/build/
  -> Nginx 子路径静态托管

当前发布集合：

源路径	站点路径	发布策略
`AI Agent知识体系大全/`	`/ai-agent/`	主知识库，排除 `00-项目控制台/`
`AI体系学习课程/`	`/ai-course/`	系统课程，排除 `99-项目管理/`
`LangChain学习手册/`	`/langchain-handbook/`	只发布手册文档、示例 README 和项目 README
根目录文档	`/root-docs/`	只发布根目录一层 `.md/.mdx/.pdf/.docx`

代码型目录不会自动发布。LangChain/、src/、test/、node_modules/、scripts/、data/、evals/ 等默认排除。

2. 本地运行

进入站点目录：

cd /Users/luhanguo/Desktop/AI/agent-docs-site

首次安装依赖：

npm install

启动本地开发服务：

npm run start

访问：

http://localhost:3000

常用命令：

npm run sync:docs
npm run build
npm run serve

说明：

npm run sync:docs：按 docs-sync.config.json 同步源文档。
npm run start：启动本地开发服务，启动前自动同步。
npm run build：生成静态站点，构建前自动同步。
npm run serve：本地预览 build/ 目录。
BASE_URL=/ai-agent-docs/ npm run build：生成可部署到 /ai-agent-docs/ 子路径的静态站点。

3. 本地构建验证

每次准备部署前执行：

cd /Users/luhanguo/Desktop/AI/agent-docs-site
npm run build
test -f build/index.html

如果部署到子路径 /ai-agent-docs/，使用：

BASE_URL=/ai-agent-docs/ npm run build
test -f build/index.html

检查关键排除目录没有进入站点：

find docs/ai-agent -path '*00-项目控制台*' -print
find docs/ai-course -path '*99-项目管理*' -print
find docs/langchain-handbook \( -path '*src*' -o -path '*test*' -o -path '*node_modules*' -o -name package.json \) -print

期望输出为空。

检查站点源同步目录中没有代码文件误入：

find docs \( -path '*data*' -o -path '*src*' -o -path '*evals*' -o -path '*fixtures*' -o -path '*node_modules*' -o -name package.json -o -name '*.ts' -o -name '*.js' -o -name '*.mjs' -o -name '*.jsonl' \) -print | sort

期望输出为空。注意这个命令检查的是 agent-docs-site/docs/，不是 build/；Docusaurus 的 build/ 会正常包含前端 .js 静态资源。

4. SSH + Nginx 部署策略

首版部署采用手动 SSH 发布，并部署到子路径 /ai-agent-docs/，避免覆盖服务器现有根路径站点：

本地 BASE_URL=/ai-agent-docs/ npm run build
  -> rsync build/ 到服务器临时目录
  -> sudo rsync 到 Nginx web root
  -> nginx -t
  -> reload nginx

推荐服务器目录：

/var/www/ai-agent-docs        # Nginx 静态站目录
/tmp/ai-agent-docs-build      # 临时上传目录

真实部署前需要确认：

项	说明
`host`	服务器 IP 或域名
`ssh user`	SSH 登录用户
SSH 端口	默认 `22` 或自定义端口
认证方式	本机 SSH key、临时 deploy key 或一次性凭据
访问域名/IP	Nginx `server_name`
部署目录	默认 `/var/www/ai-agent-docs`
访问子路径	默认 `/ai-agent-docs/`
sudo 权限	写 web root、配置 Nginx、reload 服务需要
Nginx 状态	已安装或需要初始化安装

不要在文档、代码或聊天记录中粘贴长期私钥、密码、Token。

5. 自动化脚本

推荐日常本地预览和服务器发布都走脚本，不再手动拼命令。

在仓库根目录启动本地站点：

cd /Users/luhanguo/Desktop/AI
npm run site:start

在仓库根目录部署到当前服务器：

cd /Users/luhanguo/Desktop/AI
npm run site:deploy

在站点目录也可以直接运行：

cd /Users/luhanguo/Desktop/AI/agent-docs-site
npm run local
npm run deploy:server

部署脚本会自动完成：

用 BASE_URL=/ai-agent-docs/ 构建站点。
在 sync:docs 阶段把真实 .docx 转成可阅读页面，并保留原 Word 下载链接。
上传 build/ 到 /var/www/ai-agent-docs/。
上传并确认 Nginx 子路径片段。
如果主配置还没有 include，会自动备份并插入 include。
执行 nginx -t 并 reload Nginx。
验证 /ai-agent-docs/、/ai-agent-docs/ai-agent/、/ai-agent-docs/ai-course/、/ai-agent-docs/langchain-handbook/、/ai-agent-docs/root-docs/。

脚本不会保存服务器密码。没有配置 SSH key 时，SSH 会在终端提示输入密码；配置好 SSH key 后就是完整一键部署。

Word 文档展示边界：

根目录真实 .docx 会生成同名在线阅读页，例如 /ai-agent-docs/root-docs/AI知识体系_阶段一_基础认知/。
原始 Word 文件会复制到 /ai-agent-docs/generated-doc-assets/，页面顶部提供下载入口。
._*.docx、.~*.docx、~$*.docx 等临时文件不会发布。
转换优先保证语义化阅读，不承诺 100% 保留 Word 版式；复杂排版以原文件为准。
npm run build 的 postbuild 步骤会清理 HTML/JS/JSON/CSS 等文本产物中的实际控制字符，避免异常字节污染线上链接或侧边栏。

常用环境变量：

变量	默认值	说明
`DEPLOY_HOST`	`118.193.46.228`	服务器地址
`DEPLOY_USER`	`root`	SSH 用户
`DEPLOY_PORT`	`22`	SSH 端口
`BASE_URL`	`/ai-agent-docs/`	Docusaurus 子路径
`SITE_URL`	`https://korealu.top`	验证用站点地址
`REMOTE_WEB_ROOT`	`/var/www/ai-agent-docs`	服务器静态目录
`REMOTE_NGINX_SERVER_CONF`	`/etc/nginx/conf.d/korealu.conf`	要插入 include 的 Nginx server 配置
`REMOTE_NGINX_INCLUDE`	`/etc/nginx/conf.d/ai-agent-docs-location.inc`	服务器 Nginx 子路径片段
`DEPLOY_SSH_KEY`	空	指定私钥路径，例如 `~/.ssh/id_ed25519`
`SKIP_INSTALL`	`0`	设为 `1` 时不自动安装依赖
`SKIP_BUILD`	`0`	设为 `1` 时跳过构建，只上传现有 `build/`
`DRY_RUN`	`0`	设为 `1` 时只构建和检查配置，不上传服务器
`VERIFY_URLS`	`1`	设为 `0` 时跳过线上 URL 验证

例子：

DEPLOY_SSH_KEY=~/.ssh/id_ed25519 npm run site:deploy
DRY_RUN=1 npm run site:deploy
PORT=3001 npm run site:start

6. 服务器初始化

以下命令在服务器执行，适用于 Ubuntu/Debian：

sudo apt update
sudo apt install -y nginx rsync
sudo mkdir -p /var/www/ai-agent-docs
sudo chown -R "$USER":www-data /var/www/ai-agent-docs
sudo chmod -R 755 /var/www/ai-agent-docs

如果服务器已经托管其他站点，不要直接删除默认站点或改全局配置；应新增独立 server block，并确认域名、端口和路径不冲突。

7. Nginx HTTP 配置

创建：

/etc/nginx/sites-available/ai-agent-docs.conf

示例：

server {
    listen 80;
    server_name example.com;

    root /var/www;
    index index.html;

    location = /ai-agent-docs {
        return 301 /ai-agent-docs/;
    }

    location /ai-agent-docs/ {
        try_files $uri $uri/index.html /ai-agent-docs/index.html;
    }

    location ~* ^/ai-agent-docs/.*\.(?:js|css|png|jpg|jpeg|svg|webp|ico|woff2?)$ {
        expires 30d;
        add_header Cache-Control "public, max-age=2592000, immutable";
        try_files $uri =404;
    }

    location ~* ^/ai-agent-docs/.*\.(?:pdf|docx)$ {
        add_header X-Content-Type-Options nosniff;
        try_files $uri =404;
    }
}

如果暂时只有 IP，没有域名：

server_name _;

启用配置：

sudo ln -s /etc/nginx/sites-available/ai-agent-docs.conf /etc/nginx/sites-enabled/ai-agent-docs.conf
sudo nginx -t
sudo systemctl reload nginx

try_files $uri $uri/index.html /ai-agent-docs/index.html 用来保证 Docusaurus 子路径下的深层路径刷新时不 404，也能避免没有 index.html 的分类目录直接返回 403。这里不接管 /，避免影响服务器上已有站点。

8. 首次发布

本地执行：

cd /Users/luhanguo/Desktop/AI/agent-docs-site
BASE_URL=/ai-agent-docs/ npm run build
rsync -az --delete -e "ssh -p 22" build/ deploy@example.com:/tmp/ai-agent-docs-build/
ssh -p 22 deploy@example.com 'sudo rsync -a --delete /tmp/ai-agent-docs-build/ /var/www/ai-agent-docs/ && sudo nginx -t && sudo systemctl reload nginx'

替换：

22：真实 SSH 端口。
deploy@example.com：真实用户和服务器。
/var/www/ai-agent-docs：真实 Nginx 静态目录。

9. 日常更新和删除同步

修改或新增文档后：

cd /Users/luhanguo/Desktop/AI/agent-docs-site
BASE_URL=/ai-agent-docs/ npm run build
rsync -az --delete -e "ssh -p 22" build/ deploy@example.com:/tmp/ai-agent-docs-build/
ssh -p 22 deploy@example.com 'sudo rsync -a --delete /tmp/ai-agent-docs-build/ /var/www/ai-agent-docs/ && sudo nginx -t && sudo systemctl reload nginx'

删除源文档后也执行同一套命令。rsync --delete 会把服务器上不再存在于本地 build/ 的旧页面删除。

如果线上仍然能访问旧文件，优先检查：

是否重新执行了 npm run build。
上传目录是否是 build/，而不是 docs/ 或源目录。
两次 rsync 是否都带了 --delete。
Nginx root 是否指向同一个目录。
是否有 CDN、浏览器缓存或反向代理缓存。

10. 回滚方案

首版可以使用静态目录备份：

sudo tar -C /var/www -czf /var/www/ai-agent-docs-backup-$(date +%Y%m%d-%H%M%S).tar.gz ai-agent-docs

回滚：

sudo rm -rf /var/www/ai-agent-docs
sudo mkdir -p /var/www/ai-agent-docs
sudo tar -C /var/www -xzf /var/www/ai-agent-docs-backup-YYYYMMDD-HHMMSS.tar.gz
sudo nginx -t
sudo systemctl reload nginx

后续如果部署频率提高，推荐改成 release 目录：

/var/www/ai-agent-docs/releases/20260518-143000/
/var/www/ai-agent-docs/current -> releases/20260518-143000/

Nginx root 指向 current，回滚时只切换 symlink。

11. 验收清单

本地：

BASE_URL=/ai-agent-docs/ npm run build 成功。
build/index.html 存在。
docs/ 中没有代码工程文件误入。

服务器：

sudo nginx -t 通过。
sudo systemctl status nginx 正常。
子路径首页可访问：/ai-agent-docs/。
子路径深层页面可刷新：/ai-agent-docs/ai-agent/、/ai-agent-docs/ai-course/、/ai-agent-docs/langchain-handbook/、/ai-agent-docs/root-docs/。
Word 转换页可访问，例如 /ai-agent-docs/root-docs/AI知识体系_阶段一_基础认知/。
Word 原文件可下载，例如 /ai-agent-docs/generated-doc-assets/root-docs/AI知识体系_阶段一_基础认知.docx。
LangChain/ 没有作为代码目录发布。
00-项目控制台、99-项目管理 没有发布。
.pdf/.docx 可以作为静态文件访问。

12. 常见故障

12.1 首页可访问，深层文档刷新 404

确认 Nginx 配置中有：

try_files $uri $uri/index.html /ai-agent-docs/index.html;

修改后执行：

sudo nginx -t
sudo systemctl reload nginx

12.2 构建失败

优先检查源 Markdown：

JSX 风格尖括号是否被 MDX 误解析。
代码块是否闭合。
Mermaid 语法是否正确。
本地链接是否指向未发布文件。

同步脚本会处理一部分 Docusaurus 兼容问题，但不会替代源文档质量检查。

12.3 Word 页面或 `.docx/.pdf` 访问不到

确认文件位于允许发布的 collection 中，并且扩展名在 docs-sync.config.json 的 extensions 范围内。然后重新执行：

cd /Users/luhanguo/Desktop/AI/agent-docs-site
BASE_URL=/ai-agent-docs/ npm run build
find build -name '*.pdf' -o -name '*.docx'

如果 Word 页面存在但原文件下载 404，重点检查 build/generated-doc-assets/ 是否存在对应 .docx。

12.4 Nginx reload 失败

查看配置错误和服务状态：

sudo nginx -t
sudo systemctl status nginx
sudo journalctl -u nginx --no-pager -n 80

13. 后续升级

HTTPS：域名 DNS 解析稳定后，用 Certbot 增加证书。
版本化发布：使用 release 目录和 symlink，支持快速回滚。
CI/CD：GitHub Actions 或其他流水线构建后自动 rsync。
访问日志：分析高频页面、404、静态资源命中情况。
安全响应头：按实际开放范围增加 CSP、Referrer-Policy 等配置。

14. 权威资料

Docusaurus Docs: https://docusaurus.io/docs
Docusaurus Deployment: https://docusaurus.io/docs/deployment
Docusaurus Static Assets: https://docusaurus.io/docs/static-assets
Nginx Documentation: https://nginx.org/en/docs/

1. 当前站点模型​

2. 本地运行​

3. 本地构建验证​

4. SSH + Nginx 部署策略​

5. 自动化脚本​

6. 服务器初始化​

7. Nginx HTTP 配置​

8. 首次发布​

9. 日常更新和删除同步​

10. 回滚方案​

11. 验收清单​

12. 常见故障​

12.1 首页可访问，深层文档刷新 404​

12.2 构建失败​

12.3 Word 页面或 .docx/.pdf 访问不到​

12.4 Nginx reload 失败​

13. 后续升级​

14. 权威资料​