应用安全【免费下载链接】Top10Official OWASP Top 10 Document Repository项目地址https://gitcode.com/gh_mirrors/top/Top10点击查看免费下载本文基于 OWASP Top 10 官方文档仓库Top10中的 REORGANIZATION-2025.md 展开讲清楚一次真实发生的多版本文档站重组为什么 2025 版内容不能继续寄居在 2021 目录里、如何用git mv 独立mkdocs.yml 构建编排脚本完成拆分以及如何通过自动生成的 HTML 重定向页让旧 URL 全部继续可用。读完后你将掌握一仓多站文档架构的目录规划、MkDocs 双站构建与发布流程以及面向后续版本2028、2031的可扩展维护模式。一、背景多版本共存暴露的结构性问题OWASP Top 10 文档仓库按年份组织各版本内容2003/、2004/、2007/、2010/、2013/、2017/、2021/、2025/其中 2021 与 2025 是仅有的两个活跃 MkDocs 站点版本带mkdocs.yml可直接构建的英文站点。2025 Release Candidate 开发期间新内容被临时放在/2021/docs/en/2025/并且/2021/mkdocs.yml被改造为一个同时承载 2021 与 2025 两套内容的合体站点。文档明确记录了这种做法造成的五个问题结构混乱——2021目录里同时装着 2021 和 2025 的内容维护困难——一个mkdocs.yml同时控制两个版本归属不清——无法回答哪个版本是主版本导航脏乱——站点上同时出现 Current Release 和 Release Candidate 两个区块位置错误——2025 文件本应位于/2025/docs/en/而不是 2021 目录内部。对应的解决思路即重组的四个目标是将 2025 文档移动到正确位置/2025/docs/en/为每个版本创建相互独立的 MkDocs 配置分别构建两个站点、统一部署用 HTML 重定向页保持既有 2021 URL 的向后兼容。二、被移动的文件用git mv保留历史重组的一个关键原则是git 历史不丢失所有 2025 文件均通过git mv从/2021/docs/en/2025/迁移到/2025/docs/en/。文档列出的 15 个 Markdown 文件与仓库 2025/mkdocs.yml 中nav引用的条目可以一一对照迁移前的文档/2021/docs/en/2025/迁移后/2025/docs/en/0x00_2025-Introduction.md同名引言0x01_2025-About_OWASP.md同名0x02_2025-What_are_Application_Security_Risks.md同名0x03_2025-Establishing_a_Modern_Application_Security_Program.md同名A01_2025-Broken_Access_Control.md同名A02_2025-Security_Misconfiguration.md同名A03_2025-Software_Supply_Chain_Failures.md同名A04_2025-Cryptographic_Failures.md同名A05_2025-Injection.md同名A06_2025-Insecure_Design.md同名A07_2025-Authentication_Failures.md同名A08_2025-Software_or_Data_Integrity_Failures.md同名A09_2025-Logging_and_Alerting_Failures.md同名A10_2025-Mishandling_of_Exceptional_Conditions.md同名X01_2025-Next_Steps.md同名除 Markdown 外资产文件也一并归位图片2025-algorithm-diagram.png、2025-mappings.png从/2021/docs/assets/移到/2025/docs/assets/仓库中两个文件均确认存在于 2025/docs/assets/CSSRC-stylesheet.css从/2021/docs/assets/css/移到/2025/docs/assets/css/现存于 2025/docs/assets/css/RC-stylesheet.css共享资产复制而非移动OWASP_Logo_Transp.png、TOP_10_logo_Final_Logo_Colour.png复制到/2025/docs/assets/因为两个版本站点都需要它们。注意移动 vs 复制的区别内容性文件用移动避免重复维护而两个站点共用的 Logo 用复制避免跨站点引用。三、新建的文件文档与构建脚本重组同时创建了以下文件文件作用2025/docs/en/index.md2025 版站点欢迎页列出 2025 Top 10 全部条目导航REORGANIZATION-2025.md本重组的记录文档scripts/build-all.sh编排构建 2021 与 2025 两个站点并生成兼容层scripts/generate-redirects.sh批量生成 HTML 重定向页scripts/index-redirect.html站点根跳转模板四、修改的配置文件两个站点脱钩4.1 2021/mkdocs.yml 的修改文档记录对 2021/mkdocs.yml 的修改包括site_name从 OWASP Top 10:2025 RC1 改回 OWASP Top 10:2021site_description改为 OWASP Top 10:2021新增site_url: https://owasp.org/Top10/2021/删除整个 Release Candidate 导航区块导航只保留 2021 内容。对照当前文件可以确认结果nav从Welcome Page: index.md开始到A10_2021-Server-Side_Request_Forgery_(SSRF).md与A11_2021-Next_Steps.md结束全部指向 2021 英文文档plugins中 i18nmkdocs-static-i18n配置了 11 个 localeen、ar、de、es、fr、id、it、ja、pt-BR、tr、zh-Hant、zh-TW 共 12 项其中 en 为 default。4.2 2025/mkdocs.yml 的修改对 2025/mkdocs.yml新增site_url: https://owasp.org/Top10/2025/所有导航路径由2025/...前缀改为en/...前缀即文档从版本子目录结构改为语言子目录结构导航加入Home: en/index.mdrepo_url从开发地址改为生产地址。当前文件中nav确实以en/0x00_2025-Introduction.md这样的en/前缀引用全部 15 个迁移后的文档。一个值得注意的后续演进仓库当前状态已不再是文档撰写时2025 仅英文的状态——2025/mkdocs.yml 的 i18n 插件现已配置了 cs、de、es、fa、it、ja、ko、pt-BR、zh-Hant 等多语种且 2025/docs/ 下也出现了cs/、de/、es/等语言目录。这恰好印证了文档Future Maintenance章节中添加翻译流程见第八节已被实际执行过。五、目录结构Before / After重组前后的目录形态对比引自 REORGANIZATION-2025.md与当前仓库结构一致Before问题状态/2021/ ├── docs/ │ ├── en/ │ │ ├── A01_2021-*.md # 2021 内容 │ │ ├── 2025/ # ← 2025 内容错误地放在这里 │ │ │ ├── 0x00_2025-*.md │ │ │ └── A01_2025-*.md │ │ └── index.md │ └── assets/ │ ├── 2025-*.png # ← 2025 资产错误地放在这里 │ └── css/RC-stylesheet.css # ← 2025 CSS 错误地放在这里 └── mkdocs.yml # 20212025 合体配置 /2025/ ├── docs/ │ ├── README.md │ └── assets/ └── mkdocs.yml # 指向错误路径After拆分后的状态/2021/ ├── docs/ │ ├── en/ │ │ ├── A01_2021-*.md # 仅 2021 内容 │ │ └── index.md │ └── assets/ # 仅 2021 资产 └── mkdocs.yml # 仅 2021 的配置 /2025/ ├── docs/ │ ├── en/ │ │ ├── 0x00_2025-*.md # 2025 内容 │ │ ├── A01_2025-*.md │ │ └── index.md │ └── assets/ │ ├── 2025-*.png # 2025 资产 │ └── css/RC-stylesheet.css # 2025 CSS └── mkdocs.yml # 仅 2025 的配置 /scripts/ ├── build-all.sh # 构建编排 ├── generate-redirects.sh # 重定向生成 └── index-redirect.html # 根跳转模板核心设计原则一句话概括版本目录只装本版本的内容站点配置与目录严格一一对应。六、URL 结构与向后兼容方案6.1 生产 URL 规划文档记录的目标 URL 布局https://owasp.org/Top10/→ 跳转至默认版本保留既有链接可用https://owasp.org/Top10/2021/→ 2021 站点https://owasp.org/Top10/2025/→ 2025 站点。6.2 重定向页的生成逻辑构建系统会自动生成 HTML 重定向页使旧 URL 继续可用。文档列举了三类根级页面重定向2021 英文页面原先位于站点根路径/A00_2021_Introduction/→/Top10/2021/A00_2021_Introduction//A01_2021-Broken_Access_Control/→/Top10/2021/A01_2021-Broken_Access_Control/所有原本在根路径的 2021 页面全部重定向到/Top10/2021/之下。语言目录重定向/en/→/Top10/2021/英文在 2021 站点中位于根/ar/→/Top10/2021/ar/、/de/→/Top10/2021/de/、/es/→/Top10/2021/es/等覆盖全部语言。版本内/en/子路径重定向英文从子目录提升到根之后/2021/en/→/Top10/2021//2021/en/A00_2021_Introduction/→/Top10/2021/A00_2021_Introduction//2025/en/→/Top10/2025//2025/en/A01_2025-Broken_Access_Control/→/Top10/2025/A01_2025-Broken_Access_Control/这些重定向全部由 scripts/generate-redirects.sh 在构建过程中生成。阅读脚本实现可以看到具体的工程细节脚本维护一个语言列表LANGUAGES(en ar de es fr id it ja pt-BR tr zh-Hant zh-TW)为每种语言在build/根下生成index.html重定向页英文目标为/2021/其余语言目标为/2021/$lang/对根级英文页面脚本用find $REDIRECT_DIR/2021 -maxdepth 2 -name *.html扫描构建产物为每个页面目录生成带meta http-equivrefresh与link relcanonical的跳转页对/2021/en/*与/2025/en/*旧路径脚本同样遍历构建目录逐页生成跳转页目标分别为/2021/page/与/2025/page/。从脚本源码看当前版本的跳转目标是top10.owasp.org域名下的相对根路径脚本头部注释写明 Changed URL-Base from owasp.org/Top10 to top10.owasp.org/且 scripts/build-all.sh 会在build/下写入CNAME文件内容为top10.owasp.org。也就是说文档中描述的owasp.org/Top10/前缀是重组时的部署方案后续仓库把站点迁到了top10.owasp.org子域跳转页相应改为无/Top10/前缀的绝对路径——理解这一点对阅读该仓库历史很有帮助。6.3 根跳转模板与语言选择器修复scripts/index-redirect.html 是站点根的跳转模板使用meta http-equivrefresh content0; url./2025/en/实现零延迟跳转。文档撰写时它指向 2021而当前仓库中的模板已经改为指向./2025/en/——对应文档Updating from RC to Final Release一节中更新index-redirect.html使其指向 2025的步骤说明 2025 版发布后该切换已经执行现在访问站点根会跳到 2025 版。文档还记录了一个容易被忽视的细节——语言选择器修复从2021/mkdocs.yml中删除extra.alternate区块改由 i18n 插件material_alternate: true根据site_url配置自动生成语言选择器链接。当前 2021/mkdocs.yml 中留有注释 Removed extra.alternate - the i18n plugin with material_alternate: true handles this automatically与此描述完全吻合。这样处理的好处是语言链接在本地开发与生产环境都能解析正确而手写alternate链接在部署路径变化如加上/2021/前缀后会失效。七、构建系统Makefile 目标与 build-all.sh 编排7.1 Makefile 目标一览Makefile 在重组后新增了完整的多版本目标当前实现与文档描述一致目标实际命令说明build-2021cd 2021 mkdocs build --site-dir ../build/2021只构建 2021 站点产物落在build/2021build-2025cd 2025 mkdocs build --site-dir ../build/2025只构建 2025 站点产物落在build/2025build-all./scripts/build-all.sh构建两站 生成全部兼容层build为其别名serve-2021cd 2021 mkdocs serve -a localhost:80002021 站点开发服务器端口 8000带 MkDocs live-reloadserve-2025cd 2025 mkdocs serve -a localhost:80012025 站点开发服务器端口 8001serve依赖build-all然后cd build python3 -m http.server 8000先构建两站再用 Python HTTP 服务器整体伺服clean-2021/clean-2025/clean-allrm -rf build/2021等清理构建产物clean为clean-all别名publish依赖build-all然后cd build git init -b main git add -A git commit ... git push -f gitgithub.com:OWASP/Top10.git main:gh-pages部署两站到 GitHub Pagesgenerate等价于build-2021向后兼容保留使用前需先通过install-python-requirements目标建立虚拟环境并安装 requirements.txt 中的依赖其中包括mkdocs、mkdocs-material、pymdown-extensions、mkdocs-static-i18n[material]、mkdocs-macros-plugin等——这正是两个站点使用的 Material 主题、i18n 语言切换与 macros 插件的依赖来源。7.2 build-all.sh 的完整编排scripts/build-all.sh 是一次命令构建一切的核心其执行顺序为#!/bin/bash set -e # 1. 激活虚拟环境 source venv/bin/activate # 2. 清空旧构建 rm -rf build/ # 3. 构建 2021 站点 → build/2021 cd 2021 mkdocs build --site-dir ../build/2021 cd .. # 4. 构建 2025 站点 → build/2025 cd 2025 mkdocs build --site-dir ../build/2025 cd .. # 5. 复制根跳转页 cp scripts/index-redirect.html build/index.html # 6. 写入 CNAMEtop10.owasp.org echo top10.owasp.org build/CNAME # 7. 生成全部 HTML 重定向页 ./scripts/generate-redirects.sh最终build/目录的内容与文档描述一致build/2021/—— 完整 2021 站点build/2025/—— 完整 2025 站点build/index.html—— 由index-redirect.html复制而来的根跳转页当前指向 2025build/en/、build/ar/等 —— 各类向后兼容重定向页build/CNAME—— GitHub Pages 自定义域名。make serve则直接用python3 -m http.server 8000伺服build/目录从而在本地同时预览两个版本http://localhost:8000/2021/与http://localhost:8000/2025/根路径走跳转页。而serve-2021/serve-2025两个目标走 MkDocs 自带的mkdocs serve利用 live-reload 特性用于日常编辑。7.3 部署make publish该目标先执行build-all随后在build/目录中执行git init -b main、git add -A、提交并强制推送到上游仓库的gh-pages分支。强制推送在这里是安全的因为build/每次都是全量重新生成不需要保留gh-pages上的历史。八、测试清单如何验证重组结果文档给出了一份逐项可勾选的验证清单引自 REORGANIZATION-2025.md这是验收此类站点拆分工作的实用模板make serve-2021成功启动 2021 站点make serve-2025成功启动 2025 站点2021 站点只显示 2021 内容无任何 2025 引用2025 站点只显示 2025 内容且带 RC 水印RC 阶段两个版本中所有图片均能正常加载2021 站点全部 11 个语言可用make build-all无错误完成每种语言都生成了对应重定向页根index.html正确跳转当时为跳向 2021部署后根路径、/2021/、/2025/三个 URL 均可访问旧 2021 URL 全部正确重定向原先可用的链接无 404。九、故障排查五类典型问题文档内置的 Troubleshooting 部分覆盖了该构建体系最常遇到的坑每一条都是症状 → 原因 → 解法结构值得保留原样9.1 mkdocs build 在 2025 上失败原因导航引用了不存在的文件解法检查 2025/mkdocs.yml 中所有nav路径是否都以en/...开头且对应文件确实存在于/2025/docs/en/。9.2 2025 站点图片不加载原因资产路径仍写成../../assets/迁移前的相对深度解法迁移后目录层级变浅2025 所有 Markdown 中的资产路径应统一为../assets/。9.3 重定向不生效原因generate-redirects.sh未被执行或build/目录缺失该脚本依赖已构建出的 HTML 文件来枚举页面解法直接运行 scripts/build-all.sh它会在末尾调用重定向脚本。9.4 make publish 失败原因Git 认证问题或构建本身出错解法确认 SSH key 已配置好对上游仓库的访问权限并确认build-all能独立完成。9.5 旧 2021 URL 返回 404原因HTML 重定向页未生成或未随构建产物一起部署解法检查build/en/、build/ar/等目录下是否存在index.html重定向文件。十、未来维护指南模式如何向后续版本扩展重组最重要的产出之一是它确立了加一个版本的标准作业流程。10.1 新增一个版本例如 2028按 2025 的结构创建/2028/目录docs/en/、docs/assets/、mkdocs.yml在/2028/mkdocs.yml中设置site_url: https://owasp.org/Top10/2028/在 Makefile 中增加build-2028目标cd 2028 mkdocs build --site-dir ../build/2028的写法照搬即可更新 scripts/build-all.sh把 2028 的构建加入编排若 2028 成为正式版更新scripts/index-redirect.html的根跳转目标。CONTRIBUTING.md 中也收录了相同流程Create mkdocs.yml based on 2025 version … Update build-all.sh说明该模式已被固化为仓库贡献规范。10.2 为 2025 添加翻译从 2021 复制语言目录例如/2021/docs/fr/→/2025/docs/fr/作为底稿翻译 Markdown 文件在 2025/mkdocs.yml 的 i18n 插件languages列表中新增该语言项locale、name、build: true为该语言补充nav_translations导航文案逐条翻译。仓库现状印证了这套流程2025 站点目前已配置 cs、de、es、fa、it、ja、ko、pt-BR、zh-Hant 等多个 locale其中 de、es、ko、pt-BR、zh-Hant 等带有完整的nav_translations例如 zh-Hant 的 A05 Injection: A05 注入与 2021 配置的写法完全同构。10.3 从 RC 升级到 Final 发布从 2025/mkdocs.yml 中移除RC-stylesheet.css引用RC 水印样式更新 scripts/index-redirect.html使根跳转指向 2025 而非 2021重新构建并重新部署make build-allmake publish。仓库当前的实际状态正处在这条路径之后根跳转模板已指向./2025/en/即站点根默认进入 2025 版2021 版则继续作为独立子站保留完整历史 URL 兼容。十一、影响总结与延伸阅读文档的 Impact Summary 用六条概括了重组收益值得原样保留git 历史保留所有 2025 文件经git mv迁移提交历史完整向后兼容保持既有 2021 URL 通过重定向继续可用干净分离每个版本拥有独立的配置与构建部署灵活可单独构建/伺服某个版本也可整体部署可扩展为后续版本2028、2031 等确立了模板标准工具只用mkdocs serve与mkdocs build无自研构建工具。延伸阅读REORGANIZATION-2025.md本文的原始依据重组的完整记录CONTRIBUTING.md面向维护者的构建流程与新增版本规范Makefile全部构建/部署目标的权威定义scripts/build-all.sh、scripts/generate-redirects.sh、scripts/index-redirect.html多站编排与 URL 兼容层实现2021/mkdocs.yml、2025/mkdocs.yml两个独立站点的当前配置可直接对照 i18n 插件与 nav 结构requirements.txt构建依赖清单mkdocs-material、mkdocs-static-i18n、mkdocs-macros-plugin 等。适用前提与限制本文所述构建流程假设在仓库根目录下操作依赖 Makefile 建立的venv/虚拟环境make publish需要对本仓库上游拥有gh-pages分支的推送权限读者仅能在自己的 fork 上演练部署部分。若只需本地预览make build-all make serve即可在 8000 端口看到两个版本站点与全部兼容跳转。赞分享应用安全【免费下载链接】Top10Official OWASP Top 10 Document Repository项目地址https://gitcode.com/gh_mirrors/top/Top10点击查看免费下载相关推荐OWASP Top10 官方文档仓库贡献指南多版本 MkDocs 站点构建、翻译工作流与 URL 兼容机制OWASP Top10 官方文档仓库贡献指南多版本 MkDocs 站点构建、翻译工作流与 URL 兼容机制 本文以官方 OWASP Top 10 文档仓库T应用安全OWASP Top 10 2021 文档仓库本地构建、gh-pages 部署与多语言翻译完整指南OWASP Top 10 2021 文档仓库本地构建、gh pages 部署与多语言翻译完整指南 本文以 OWASP Top 10 2021 官方文档仓库 2应用安全如何快速配置LX Music聚合音源免费解锁全网无损音乐的终极指南如何快速配置LX Music聚合音源免费解锁全网无损音乐的终极指南 你是否厌倦了在不同音乐平台间来回切换只为找到一首歌是否因为版权限制无法享受真正的音乐自由音视频上一篇RustFS Hotpath Warp A/B 性能验证手册ABBA 门禁与回归门控实战指南下一篇agency-agents 项目 Spatial Data Scientist 空间数据分析师 Agent 实战指南空间统计、聚类与预测建模全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考