AutoDoc 文档系统

作者：InotArt 更新时间：2026 年 5 月 27 日

温馨提示

本文默认你已经具备基础 TOML 阅读能力。如果你不熟悉 TOML，可以先阅读 TOML 中文官网，或者把配置片段交给 AI 辅助解释。

AutoDoc 只负责维护配置文件中的说明性注释和少量系统元数据。它不是配置编辑器，也不会替你判断某个配置值是否适合你的服务器。

为什么需要 AutoDoc

Qexed 处于快速开发阶段，配置项会频繁新增、迁移或调整。如果每个 TOML 配置文件都手写注释，维护成本很高，并且旧版本升级时容易出现注释丢失、注释过期、字段说明与当前程序行为不一致等问题。

AutoDoc 的目标是让配置文件保持可读：程序启动或初始化配置时，自动补齐缺失字段，并把字段说明、警告、迁移提示等信息写回到配置文件中。

它会做什么

AutoDoc 会处理这些内容：

  • 为配置项生成或更新说明注释。
  • 根据语言生成中文或英文注释。
  • 写入当前 Qexed 构建的版本哈希。
  • 为新增配置项补齐默认值。
  • 将敏感字段迁移到 .secrets 文件，并在主配置中显示 <stored in .secrets>。
  • 对声明为拆分配置的内容生成独立 TOML 文件。

AutoDoc 不会做这些事：

  • 不会修改你写在 AutoDoc 管理区域外的普通注释。
  • 不会自动优化你的配置值。
  • 不会联网拉取文档。
  • 不会把 .secrets 里的真实密钥写回主配置。

何时运行

AutoDoc 在 Qexed 读取或创建配置文件时运行。常见场景包括：

  • 首次启动服务端并生成默认配置。
  • 使用初始化参数生成配置。
  • Qexed 升级后再次启动，旧配置需要补齐新字段。
  • 指定语言启动时，需要刷新配置注释语言。

默认情况下 AutoDoc 是启用的。你可以通过配置文件内的 auto_doc_setting_enable 禁用当前文件的 AutoDoc 注释更新，也可以通过程序启动参数在全局层面禁用，具体以当前版本启动参数为准。

文件头字段

每个由 Qexed 管理的 TOML 配置文件顶部都会包含 AutoDoc 文件头：

# ==== AutoDocHeader ====
# 官方文档：https://doc.qexed.com/docs/autodoc/
# 请不要修改 auto_doc_system_ 开头的字段
# 例如: auto_doc_system_lang
# 这些设置是用于自动更新配置文件语言自动注释的
# 但是您可以修改 auto_doc_setting_ 开头的字段
# auto_doc_setting_lang:当前文件独立语言,若为空则使用全局语言
# auto_doc_setting_enable:启用AutoDoc功能，该功能可自动为字段根据语言、版本等信息更新注释,以及可选的值等信息
# 在 "=======================" 下面的注释都不会被系统修改
# 但是在 "=======================" 上面的注释都会被系统修改，请不要修改
# =======================
auto_doc_system_version_hash = "ce1d867cacb7f70f70f1cffb534fae132d6ec57d"
auto_doc_system_lang = "zh-CN"
auto_doc_setting_lang = ""
auto_doc_setting_enable = true

auto_doc_system_version_hash

当前生成或刷新 AutoDoc 时使用的 Qexed 构建提交哈希。这个值由程序自动更新，用于判断配置注释来自哪个版本。

不要手动修改这个字段。手动修改不会改变 Qexed 版本，也不会触发降级或升级逻辑。

auto_doc_system_lang

当前文件实际使用的 AutoDoc 注释语言。默认通常是 zh-CN。

这个字段属于系统字段，程序会根据全局语言和当前文件语言设置自动更新。

auto_doc_setting_lang

当前配置文件的独立语言设置。

为空时使用全局语言。例如你希望主配置使用中文，但某个单独配置文件使用英文，可以设置：

auto_doc_setting_lang = "en"

下一次 AutoDoc 运行时，auto_doc_system_lang 会更新为实际使用的语言。

auto_doc_setting_enable

当前配置文件的 AutoDoc 开关。

auto_doc_setting_enable = true

设置为 false 后，AutoDoc 不会刷新该文件中的字段说明注释，但配置读取仍会继续进行。注意，禁用注释更新不等于禁用配置读取，也不等于禁用 Qexed 功能。

注释保护规则

AutoDoc 只会更新特定标记之间的内容：

# ======= AutoDoc =======
# 服务器监听地址
# =======================
ip = "0.0.0.0:25565"

如果你在标记外写自己的注释，AutoDoc 会保留：

# ======= AutoDoc =======
# 服务器监听地址
# =======================
# 这是我的注释，AutoDoc 不会修改这一行
ip = "0.0.0.0:25565"

不要把自定义注释写进 # ======= AutoDoc ======= 和 # ======================= 中间。这个区域会被 AutoDoc 覆盖。

字段说明内容

一个字段的 AutoDoc 注释可能包含多段内容：

  • 基础说明：字段的用途。
  • 高危警告：错误配置可能造成明显安全风险或破坏性影响。
  • 警告：需要管理员注意的行为。
  • 即将弃用：字段仍可用，但未来可能移除。
  • 已被弃用：字段已不推荐使用。
  • 迁移建议：从旧字段或旧行为迁移到新字段的说明。

示例：

# ======= AutoDoc =======
# 启用 Mojang 正版验证
#
# 警告：
# 关闭正版验证会允许离线用户名，并增加身份冒用风险。
# =======================
online_mode = true

新字段补齐

升级 Qexed 后，如果默认配置中新增了字段，AutoDoc 会把缺失字段补到现有配置文件中。

补齐逻辑以当前版本的默认配置结构为准。已有字段的值会保留，缺失字段使用当前版本默认值。

这意味着你升级后应当检查新增字段的默认值是否符合你的服务器需求，尤其是安全、网络、权限、存档和大厅相关配置。

敏感字段与 .secrets

部分字段属于敏感信息，例如 token、数据库密码、代理密钥等。AutoDoc 会把这些字段的真实值移动到同目录下的 .secrets 文件中，并在主配置文件里显示占位符：

download_token = "<stored in .secrets>"

假设主配置文件是：

config/qexed.toml

对应的敏感信息文件通常位于：

config/.secrets/qexed.toml

建议：

  • 不要公开 .secrets 目录。
  • 不要把 .secrets 提交到公共仓库。
  • 如果你已经公开过真实 token 或密码，应立即更换。

拆分配置文件

Qexed 支持把部分大型配置拆分到独立 TOML 文件。AutoDoc 会在读取主配置时合并这些拆分文件，在写回时再按规则拆分出去。

例如未来某些配置可能从：

config/qexed.toml

拆分到：

config/qexed.d/example.toml

这类拆分文件仍然是 Qexed 配置的一部分。编辑时要保持 TOML 语法合法，并避免移动到 AutoDoc 不认识的目录。

多语言行为

AutoDoc 的语言选择优先级如下：

  1. 程序运行时显式指定的语言。
  2. 当前文件的 auto_doc_setting_lang。
  3. 当前文件已有的 auto_doc_system_lang。
  4. 默认语言 zh-CN。

如果你只是希望服务端运行语言为中文，通常不需要修改 AutoDoc 字段。只有在某个配置文件需要单独使用另一种注释语言时，才需要设置 auto_doc_setting_lang。

推荐编辑方式

推荐只编辑实际配置值和 AutoDoc 管理区外的自定义注释：

# ======= AutoDoc =======
# 服务器监听地址
# =======================
# 局域网测试端口
ip = "0.0.0.0:25565"

不推荐做这些事：

  • 删除 auto_doc_system_ 字段。
  • 修改 # ==== AutoDocHeader ==== ... # ======================= 文件头内部说明。
  • 修改 # ======= AutoDoc ======= ... # ======================= 字段说明内部内容。
  • 把敏感值从 .secrets 手动复制回主配置并提交到仓库。

常见问题

我写的注释会被删吗？

只要注释不在 AutoDoc 管理区内，就不会被 AutoDoc 主动覆盖。

为什么我的配置里出现 <stored in .secrets>？

这是敏感字段占位符，真实值已经保存到 .secrets 文件中。Qexed 读取配置时会把 .secrets 中的值覆盖回运行时配置。

禁用 AutoDoc 后配置还会生效吗？

会。auto_doc_setting_enable = false 只影响注释刷新，不代表禁用配置文件本身。

为什么升级后配置文件多了一些字段？

当前版本新增了配置项。AutoDoc 会根据默认配置补齐缺失字段，避免旧配置在新版本中缺少必要项。

我可以删除 AutoDocHeader 吗？

不建议。即使删除，AutoDoc 下次运行时也可能重新生成文件头。需要隐藏说明时，应优先考虑禁用 AutoDoc，而不是手动破坏系统字段。

最小示例

一个带自定义注释的配置片段可以这样写：

# ==== AutoDocHeader ====
# 官方文档：https://doc.qexed.com/docs/autodoc/
# =======================
auto_doc_system_version_hash = "ce1d867cacb7f70f70f1cffb534fae132d6ec57d"
auto_doc_system_lang = "zh-CN"
auto_doc_setting_lang = ""
auto_doc_setting_enable = true

# ======= AutoDoc =======
# 运行时语言
# =======================
language = "zh-CN"

[server]
# ======= AutoDoc =======
# 服务器监听地址
# =======================
# 本地测试用端口
ip = "0.0.0.0:25565"

AutoDoc 下次运行时会刷新管理区内的说明，但会保留 # 本地测试用端口 这一类自定义注释。

编辑此页面