docs-stratego 是一个“单站点 + 页面级权限”的文档聚合仓。它的核心目标不是把源仓文档改写成另一套结构，而是：
- 让源仓在自己的
docs/下按统一标准维护文档 - 用 Git submodule + sparse-checkout 只展开外部源仓的
docs/ - 在构建前根据根
docs/index.md的全站清单生成导航和权限清单 - 用 MkDocs 生成单个静态站点
- 用 Casdoor + oauth2-proxy + Nginx 对私有页面做登录控制
- 默认关闭匿名全文搜索，避免私有内容进入公开搜索索引
docs/本仓自己的标准化文档源，同时也是外部源仓的写法示例src/CLI、稀疏同步、元数据解析、站点构建和权限清单生成逻辑scripts/deploy_remote.sh面向完整仓库工作区的全量重建与应急部署入口；日常同步与构建统一走docs-strategoCLI，标准生产服务器不依赖它做日常发布deploy/Casdoor、oauth2-proxy 与宿主机 Nginx 配置模板
uv sync --extra site
uv run docs-stratego dev --project-root .本地快速重建并启动预览：
uv run docs-stratego dev --project-root .如果要在本机模拟服务器侧的远程拉仓行为：
uv run docs-stratego dev --project-root . --source-mode remote如果你只想做一次构建、不启动本地预览：
uv run docs-stratego dev --project-root . --build-onlydocs-stratego dev 内部会顺序执行 sync -> build -> mkdocs serve；--build-only 时执行 mkdocs build。
注意：
- 当前
docs-stratego dev在source_mode=local下会自动监听根仓docs/、本地源仓docs/和config/source-repos.json - 当前
source_mode=remote仍然是一次性预演；如果你改了远程输入配置后要重新确认，请重新运行docs-stratego dev --source-mode remote
根仓本地开发需要 site extra，因为 dev / mkdocs build 依赖 mkdocs 与 mkdocs-material；外部源仓侧的轻量命令默认不需要这组依赖。
如果虚拟环境或缓存异常，直接删除 .venv 后重新执行：
rm -rf .venv
uv sync --extra site当前正式配置已经包含 6 个项目：
docs-strategocrawler4jstratixride-loopshanforgectrip_crawler
当前配置文件已经支持同一仓库条目下的两种来源模式：
local本地调试直接读取本机项目目录中的docs/remote远程构建先初始化 submodule，再在子仓内显式fetch + checkout目标分支，并只保留顶层docs/
因此本地预览和 GitHub Actions 会走同一套同步逻辑，只是 source mode 不同；开发环境统一使用 docs-stratego dev，CI 和发布链路仍保持 docs-stratego sync 与 docs-stratego build 分步执行。
正式公开标准见 source-docs-standard.md。
最关键的约束是：
- 每个目录都必须有
index.md - 只有根
docs/index.md声明mkdocs.nav - 根
docs/index.md的正文只写简介和维护说明，不再重复写目录树或章节清单 - 页面私有化只允许在根
docs/index.md的页面节点中声明 - 页面节点除了
*.md，还可以声明*.openapi.*与*.mcp-tools.*契约文件 - 已声明的 OpenAPI 文件会自动生成 Scalar API Reference 页面；已声明的 MCP tools 快照会自动生成工具参考页，并保留原始
.yaml/.json下载地址 - 未声明的 Markdown 页面直接视为构建错误
源仓接入、自动联动、移除和 CLI 命令说明见 子仓接入指南。 本地开发与预览方式见 本地开发与预览。
- Casdoor：本地账号密码 + GitHub 登录
- oauth2-proxy：提供标准
auth_request接口 - Nginx：服务静态站点，并根据生成的私有页面路径拦截请求
- 运行时配置文件：
deploy/casdoor/app.conf、deploy/oauth2-proxy/oauth2-proxy.cfg - 推荐发布方式：GitHub Actions 在 Runner 侧构建
site/与private_locations.conf，再把site/发布到/var/www/docs-stratego、把private_locations.conf安装到/etc/nginx/snippets/docs-stratego/private_locations.conf；这两份构建产物会作为 artifact 保留 7 天，用于validate -> deploy作业交接和短期排障；Docker 认证服务通常只在首次部署或运行时配置变更时更新
部署说明见 deployment-guide.md。
如果是云服务器私有化部署，请优先阅读：