网络安全网络IDS【免费下载链接】zeekZeek is a powerful network analysis framework that is much different from the typical IDS you may know.项目地址https://gitcode.com/gh_mirrors/ze/zeek点击查看免费下载Zeek 的官方文档托管于 docs.zeek.org是一个基于 Read the Docs 与 Sphinx 的 reStructuredText 工程其全部源文件都存放在仓库的doc/目录中。本文以 doc/README.md 为骨架结合 doc/conf.py、doc/Makefile、ci/update-zeekygen-docs.sh 与 doc/ext/zeek.py 等仓库内实现完整讲解目录组织、Zeekygen 自动参考文档的生成、本地构建、以及 Read the Docs 托管与重定向维护的端到端流程。读完本文你将能独立搭建 Zeek 文档的本地构建环境、重新生成全部脚本参考页并理解线上文档的版本与跳转机制。文档工程概览结构与定位Zeek 文档工程遵循标准 Sphinx 项目布局。文档根目录是仓库中的doc/其中几个关键文件承担了不同职责doc/conf.py —— 顶层 Sphinx 配置定义扩展、主题、版本号与 HTML 输出选项doc/Makefile —— 提供html、livehtml、linkcheck等构建目标doc/requirements.txt —— 声明 Python 构建依赖及版本doc/index.rst —— 文档主入口包含顶层 toctree 与版本说明doc/redirects.yml —— 定义线上 URL 的 404 重定向规则doc/ext/ —— 存放自定义 Sphinx 扩展zeek.py、zeek_pygments.py、spicy-pygments.py、literal-emph.py。文档内容的主体则是数百个.rst文件分布在 doc/about/、doc/tutorial/、doc/reference/、doc/advanced/、doc/scripts/ 等子目录中覆盖安装、脚本教程、框架参考、集群部署与开发维护等主题。添加新文档的标准做法新增页面时只需在doc/下添加新的.rst文件然后在某个toctree目录树中引用它Sphinx 便会把它纳入构建与导航。以主入口 doc/index.rst 为例.. toctree:: :maxdepth: 2 :caption: Table of Contents get-started about/index tutorial/index reference/index customizations advanced/index acknowledgementsindex.rst还承担了文档版本选择说明docs.zeek.org 默认指向最新的current发布版用户可通过横幅中的下拉菜单切换版本最常用的三个版本是en/current当前发布、en/lts长期支持版与en/master持续开发版。自定义 Sphinx 域zeek.py 扩展Zeek 文档使用 doc/ext/zeek.py 定义了一个名为zeek的自定义 Sphinx 域Domain它注册了type、namespace、id、keyword、enum、attr、field等对象类型及对应指令并实现了:zeek:see:这类交叉引用角色。这一机制的核心用途是链接到 Zeekygen 自动生成的脚本参考文档ZeekGeneric基类支持source-code选项可在签名上附加View Source Code链接指向{zeek_code_url}/scripts/{path}#L{start}-L{end}由 doc/conf.py 中的zeek_code_version与zeek_code_url拼接而成ZeekType/ZeekField配合会把 record 类型的字段自动汇总渲染为一个 Fields 字段列表ZeekEnum会捕获Notice::Type枚举并交给ZeekNotices索引类生成独立的 Zeek Notice Indexmerge_domaindata处理并行构建模式下对象表合并保证:zeek:see:的跨文件解析稳定。在正文中使用时形如.. zeek:see:: SSL::extract_issuer_distinguished_name该扩展在 doc/conf.py 中被注册进extensions列表extensions [ zeek, sphinx.ext.todo, zeek_pygments, spicy-pygments, literal-emph, sphinx.ext.extlinks, ]自动生成文档的编辑规则Zeekygen 生成的参考文档多数位于scripts/目录下或文件名以 autogenerated 开头。修改这类自动生成文档时应去其对应的 Zeek 源文件编辑而不是直接改.rst。例如要修改scripts/base/init-bare.zeek.rst中的内容应编辑的是../scripts/base/init-bare.zeek相对doc目录。这一点在 doc/README.md 中有明确说明其根因在于 Zeek 脚本中的注释与属性会被 Zeekygen 提取为参考页内容。生成 Zeekygen 参考文档Zeekygen 是 Zeek 内置的文档生成器它扫描脚本源码并输出对应的.rst参考页。完整流程分为两步先编译 Zeek再运行更新脚本。前置条件从源码构建 ZeekZeekygen 需要可执行的zeek二进制来解析脚本并提取文档信息因此必须先从源码构建 Zeek。构建完成后在源码根目录运行文档更新脚本../ci/update-zeekygen-docs.sh注意脚本路径update-zeekygen-docs.sh位于 ci/update-zeekygen-docs.sh在doc/目录下执行时应写为../ci/update-zeekygen-docs.sh。脚本内部做了什么阅读 ci/update-zeekygen-docs.sh 的源码可以看到其关键步骤清理可能干扰的 Zeek 环境变量ZEEK_DISABLE_ZEEKYGEN、ZEEK_DEFAULT_LISTEN_ADDRESS等确保生成的文档值与默认脚本一致定位build/zeekygen-test.conf作为 Zeekygen 的配置文件输出目录默认指向doc/也可通过第一个命令行参数指定其他输出目录设置ZEEK_SEED_FILE指向testing/btest/random.seed并开启ZEEK_ENABLE_ZEEKYGEN_WARNINGS1通过zeek -X $conf_file zeekygen依次生成六类内容printf script\t*\t$scripts_output_dir/ $conf_file # 全部脚本参考页 generate_index script_index autogenerated-script-index.rst generate_index package_index autogenerated-package-index.rst generate_index file_analyzer autogenerated-file-analyzer-index.rst generate_index proto_analyzer autogenerated-protocol-analyzer-index.rst generate_index packet_analyzer autogenerated-packet-analyzer-index.rst若当前分支匹配release/.*会把 doc/conf.py 中的zeek_code_version改写为该 release 分支名保证源码链接指向对应版本最后检查doc/目录是否有未提交变更并给出提示。生成的脚本参考页落在 doc/scripts/每脚本一个.rst索引文件落在 doc/reference/zeekscript/如autogenerated-script-index.rst。是否必须提交生成结果官方建议Zeek 通过.github/workflows/generate-docs.yml自动生成这批文档因此通常无需手动提交生成的变更文件。此外生成结果与构建配置相关——例如在 macOS 上不会生成 AF_Packet 的相关文档不同平台/配置下产物可能略有差异。本地重新生成的主要价值是预览改动效果。本地构建文档安装依赖构建文档前需确认环境具备以下依赖依赖说明Python 解释器版本 ≥ 3.10Sphinx文档构建引擎doc/requirements.txt 中锁定Sphinx7.4.7Read the Docs Sphinx 主题sphinx_rtd_theme锁定3.0.2GitPython用于生成过程中的 Git 交互使用 pip 一键安装全部依赖pip3 install -r requirements.txt仓库中 doc/requirements.txt 的完整内容为Jinja23.1.6 Pygments2.20.0 sphinx-rtd-theme3.0.2 Sphinx7.4.7其中注释说明Sphinx 7.4.7 是支持 Python 3.10 的最后一个版本系列而 7.4.x 之前的版本保留了对 Python 3.9 的支持。执行构建在doc/目录下运行make即可make构建完成后HTML 文档会输出到build/html目录用浏览器打开其中的index.html即可预览。doc/Makefile 实际调用的命令是html: builddir sphinx-build -j $(NUMJOBS) -b html $(SPHINXOPTS) . ./build/html其中NUMJOBS ? auto允许并行构建加速。实时预览与链接检查编辑 reST 文件时可使用livehtml目标获得热重载预览需额外安装sphinx-autobuildpip3 install sphinx-autobuild make livehtmldoc/Makefile 中livehtml会忽略.git、.lock、.pyc等文件并在独立浏览器窗口中实时渲染变更。此外还有链接检查目标make linkcheck它调用sphinx-build -b linkcheck校验文档内全部外链。为保证检查稳定doc/conf.py 中配置了大量linkcheck_ignore规则如 GitHub 锚点、MaxMind 需登录的链接、Zeek 官方社区链接等并设置linkcheck_workers 1以规避外部站点限流。构建配置的关键细节doc/conf.py 中的几个配置项直接决定产出效果版本注入version默认值为source随后尝试读取../VERSION文件即仓库根目录的 VERSION成功则以其中内容覆盖作为|version|与|release|html_title因此显示为Book of Zeek (版本)主题与品牌html_theme sphinx_rtd_theme侧边栏 Logo 使用 doc/images/zeek-logo-sidebar.pngfavicon 使用 doc/images/zeek-favicon.ico自定义 CSSsetup()中通过app.add_css_file(theme_overrides.css)加载 doc/_static/theme_overrides.css并注册自定义的 Zeek 语法高亮 lexerZeek 代码链接zeek_code_version master、zeek_code_url https://github.com/zeek/zeek/blob/{zeek_code_version}被zeek.py扩展用于生成查看源码链接release 分支构建时会被更新脚本改写排除模式exclude_patterns跳过reference/zeekscript/autogenerated-*因为这类文件由更新脚本生成、不应参与手工维护外部链接简写通过extlinks定义了:slacklink:、:discourselink:、:spicylink:三个便捷角色。线上托管Read the Docs 与重定向Zeek 文档托管在 Read the DocsRTD上最终通过自定义域名 docs.zeek.org 对外服务。RTD 构建配置仓库根目录的 .readthedocs.yml 声明了 RTD 侧的构建参数version: 2 formats: - htmlzip build: os: ubuntu-24.04 tools: python: 3.13 python: install: - requirements: doc/requirements.txt sphinx: configuration: doc/conf.py即 RTD 在 Ubuntu 24.04 Python 3.13 环境中按doc/requirements.txt安装依赖并以doc/conf.py作为 Sphinx 配置构建同时产出 htmlzip 打包格式。域名跳转机制文档工程存在一个特殊的永远构建失败的 RTD 项目slug 为zeek。其存在目的是RTD 只有在页面 404 时才会激活重定向因此需要这个恒失败项目占位使所有访问zeek.rtfd.io或zeek.readthedocs.io的请求都被引导至 docs.zeek.org——这两个 URL 原本应是主项目的地址只是官方在文档开发早期才取得zeek这个 RTD slug实际内容一直构建在zeek-docs项目下。404 重定向维护URL 重定向统一记录在 doc/redirects.yml 中由 zeek-aux 仓库中的doc-redirects外部脚本负责维护与部署。该文件头部注释给出了每个条目的完整语义from_url要重定向的源 URLto_url目标 URLtype默认page也可为exact等类型enabled布尔值默认truehttp_status301永久或302临时默认301description可选说明会显示在 RTD 管理界面。规则按文件中的顺序生效first-hit-wins先匹配先胜出。例如历史上/configuration/index.html被 301 指向/cluster-setup.html#cluster-configuration/install/*统一指向/install.html/logs/*映射到/reference/logs/:splat。文件注释还特别提醒RTD 免费套餐限制 100 条重定向尽量用目录级规则代替逐页规则。此外/en/stable/*→/en/current/:splat、/en/latest/*→/en/master/:splat这类规则将稳定版/最新版 URL 收敛到 current/master 版本路径。子项目与自动构建RTD 还为 Broker、Package Manager、Spicy 等组件配置了子项目subprojects使它们的文档可以通过 docs.zeek.org 自定义域名下的子路径访问。构建侧RTD 通过 webhook 对推送到zeek-docs的提交自动触发构建但若某个 tag 被移动指向了不同提交通常需要进入 RTD 网页界面手动处理在 Versions 中编辑对应版本wipe 旧文档再在 Builds 下手动触发该版本 tag 的重建。常见问题与排查要点生成的参考页有差异Zeekygen 输出受构建平台影响如 macOS 下不生成 AF_Packet 文档且 CI 会自动重新生成无需手工提交变更构建缺依赖确认 Python ≥ 3.10并使用pip3 install -r doc/requirements.txt安装与 doc/requirements.txt 一致的锁定版本make报版本文件缺失conf.py启动时会读取../VERSION若在未检出该文件的目录中构建会直接退出——从 Zeek 源码根目录的doc/子目录构建即可避免链接检查误报已知外部链接GitHub 锚点、MaxMind、try.zeek.org 等已在 doc/conf.py 中配置忽略若新增类似域名可仿照补充linkcheck_ignore规则修改自动生成文档不生效请改对应的.zeek源文件如 scripts/base/init-bare.zeek而非.rst再重新运行../ci/update-zeekygen-docs.sh。结语Zeek 的文档体系是一套源码驱动的完整工程doc/下的 reST 源文件 自定义 Sphinx 域构成了静态内容骨架Zeekygen 从脚本源码自动生成参考页ci/update-zeekygen-docs.sh串联起编译与生成流程最终由 Read the Docs 托管、redirects.yml维护 URL 映射通过 docs.zeek.org 对外提供带版本选择的文档服务。理解这条链路后无论是贡献新章节、修正脚本注释后的参考页还是排查线上链接问题都能定位到仓库中对应的确切文件与命令。赞分享网络安全网络IDS【免费下载链接】zeekZeek is a powerful network analysis framework that is much different from the typical IDS you may know.项目地址https://gitcode.com/gh_mirrors/ze/zeek点击查看免费下载相关推荐CodeIgniter 官方用户指南的 Sphinx 文档构建指南从 reST 源码到 HTML 的完整流程CodeIgniter 官方用户指南的 Sphinx 文档构建指南从 reST 源码到 HTML 的完整流程 导读 本文围绕 CodeIgniter 3 仓库后端Web框架MLX 文档构建指南从 Doxygen、Sphinx 到 GitHub Pages 的完整工作流MLX 文档构建指南从 Doxygen、Sphinx 到 GitHub Pages 的完整工作流 本文以 MLXApple silicon 上的机器学习数组人工智能机器学习深度学习本地部署Dask 官方文档本地构建指南从源码用 Sphinx 生成 HTML 文档Dask 官方文档本地构建指南从源码用 Sphinx 生成 HTML 文档 本文介绍如何在当前 Dask 开源仓库中构建一份完整的本地 HTML 版官方文档大数据数据分析任务调度上一篇Visual C运行库修复5分钟解决Windows程序启动问题的终极指南下一篇HS2-HF Patch实战指南从零开始打造你的专属游戏体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考