贡献指南与开放任务

为什么不去建设《FreeBSD 手册》

FreeBSD 项目对除季度报告外的实质性 PR 多采取长期搁置的处理方式。从提交数据来看，freebsd-doc 项目的活跃度在过去十余年持续走低：

使用统计分析 git 项目[EB/OL]. [2026-03-26]. https://gist.github.com/ykla/6c3df44c371d37fc3196ddf5fa87ce5f 对 freebsd-doc 进行分析的结果参见：freebsd-doc-2025 分析报告[EB/OL]. [2026-03-26]. https://gist.github.com/ykla/363bf922d0785d0b02dd43f8289368db。

2005–2006 年：第一次显著下滑
2015–2016 年：第二次大幅下滑

该项目结构复杂且混乱，例如在翻译过程中部分数据引用的可复用性难以判断，即使对于维护者而言亦是如此。

此外，其安全报告的文件名包含英文冒号 :，这在 Windows 系统中属于非法字符，导致整个项目无法在 Windows 环境下正常检出：

PS C:\Users\ykla> git clone https://github.com/freebsd/freebsd-doc
Cloning into 'freebsd-doc'...
remote: Enumerating objects: 617155, done.
remote: Counting objects: 100% (294/294), done.
remote: Compressing objects: 100% (120/120), done.
remote: Total 617155 (delta 217), reused 219 (delta 174), pack-reused 616861 (from 4)
Receiving objects: 100% (617155/617155), 483.71 MiB | 786.00 KiB/s, done.
Resolving deltas: 100% (358420/358420), done.
error: invalid path 'website/static/security/advisories/FreeBSD-EN-04:01.twe.asc' # 观察 FreeBSD-EN-04:01.twe.asc，该文件名在 Windows 下是非法的
fatal: unable to checkout working tree
warning: Clone succeeded, but checkout failed.
You can inspect what was checked out with 'git status'
and retry with 'git restore --source=HEAD :/'

贡献指南概述

若您希望将教程收录至本书，可通过以下方式提交：

若您熟悉 GitHub 操作，可点击桌面端网页右侧的“编辑此页”按钮进入项目进行编辑。本项目采用 Markdown 语法配合 GitBook 平台，易于上手（具体操作详见项目 WiKi）。
若上述方式存在困难，您也可发送 PDF、Word 或 TXT 格式的文档至电子邮箱 [email protected]（我们将在 3 个工作日内回复。若未收到回复，请更换邮箱再次发送或提交 issue）；若有视频教程，建议提供各大云盘的分享链接。

本书现收录以下类型的内容：

一切与 BSD 相关（包括但不限于 FreeBSD、OpenBSD、NetBSD）及各种体系架构的教程。您既可以扩充现有教程，也可以创建新的章节。
下方的 ToDo 列表或 GitHub Project 中的任务。
您亦可在文学故事章节分享您与 BSD 的故事及个人心得体会。

基本原则与方法论

基本原则

内容应尽可能详尽且基础，勿假定读者具备任何使用背景
介绍大型软件（如 IDE、Java）时，请注明软件版本号
引用应注重权威性、时效性与准确性。优先采用原始文献，次选二手文献，避免使用三手文献
引用其他网站内容时，请核实其内容是否真实可信，尽量查阅一手来源而非直接引用网站内容
请提交至 main 分支
请避免学术不端行为，参见：高等学校预防与处理学术不端行为办法[EB/OL]. [2026-03-26]. https://www.gov.cn/zhengce/2016-07/19/content_5713390.htm （AIGC 相关规定除外）
请遵守 FreeBSD 中文社区行为规范
所有 AIGC（AI-Generated Content，人工智能生成内容）必须经过人工二次确认，核实其原始出处与来源的可靠性，不得直接提交。但纯粹翻译可作为例外绕过本规定。任何人对所提交内容自行负责，无论其是否由 AIGC 生成

使之成为“一本书”，而不仅是字典或手册

若某一技术在最新版本中已被移除，应及时移除其在本书中的对应内容
使全书语气温和而坚定
在尽量减少原文引用的前提下，重写各章节内容并删除冗余部分
实现 BSD 中文文档协作方式的现代化与简化：
- 自动化（CI 检查、预览、生成 HTML/PDF）
- 仅使用最基础的 Markdown 语法，避免复杂扩展和繁琐流程
- 技术与选材应与时俱进，确保内容的现代化
严格验证每一部分内容：
- 参考文献：不仅要求来源可查，更要求来源可信
- 原理性内容：
  - 追溯至具体的 FreeBSD 源代码文件、提交记录或函数
  - 明确引用相关标准、规范或法律文件
  - 分析其设计哲学与开发思路
- 操作性内容：应在 FreeBSD 环境中亲自测试，确保可复现
审视原作者的开发哲学与理念，评价其合理性，并尝试简单参与相关项目
指出并修正上游官方手册中的错误或过时内容
生成英文版本

细则

非拉丁字符与拉丁字符之间应添加空格（中英文/数字之间应有一个半角空格），许多 Markdown 格式化工具可自动完成此操作
不应使用 sudo 而应使用 # 代替，除非是特殊情况（如讲解如何使用 sudo 本身）；普通用户权限请使用 $ 表示
安装软件时，请提供 pkg（FreeBSD 的二进制包管理器，用于安装、更新和管理预编译软件包，提供依赖关系解析和版本管理功能）或 ports 两种方法，除非极不建议使用 pkg（如特定内核模块等）
请注意版权问题。引用内容或受到启发时，请备注文章链接出处，必要时可使用互联网档案馆进行快照保存
编辑时请尽量以最新的 FreeBSD RELEASE（FreeBSD 的正式发布版本，经过充分测试和稳定化，适合生产环境使用，每个 RELEASE 版本均有长期支持周期）为基准，绝对避免出现 pkg_add 等过时内容。如有必要，必须注明相关版本
关于编写时长，理论上会持续进行，跟随每个 FreeBSD 大版本迭代更新
若因各种原因无法立即验证所写内容的正确性，请编辑者添加“警告：以下内容为理论，未经实际测试，仅供参考，如可使用请提交 issue 以移除本标签。”的提示标签进行区分
不应在文学故事章节进行除错别字和排版以外的删减
请勿使用 Gitee 等境内无法确保信息安全与数据稳定的平台（此类平台无法保证文件的长期可访问性，不适合存放需长期归档的内容，未来存在无法获取文件的重大风险）
进行错别字修改时，请务必确认其确为错别字，可参考《现代汉语词典》第 7 版等资料进行佐证

实用附录

如何使用 Git 拉取本项目

技巧
您完全可以通过 GitHub 在线完成所有提交。

本项目体积较大，使用 Git 拉取时可能导致缓冲区溢出，可通过修改 Git 配置文件来扩大缓冲区。

以下是一个可用的 ~/.gitconfig（在 Windows 系统中的位置为 C:\Users\你的用户名\.gitconfig）的文件示例：

[filter "lfs"]
	required = true
	clean = git-lfs clean -- %f
	smudge = git-lfs smudge -- %f
	process = git-lfs filter-process
[user]
	name = # 你的用户名
	email = # 你的邮箱
	signingkey = # 你的密钥 ID，使用密钥签名时需要
[commit]
	gpgsign = true # 使用密钥签名时需要
[core]
	autocrlf = true # 自动调整末尾回车与换行
[http]
	proxy = http://localhost:7890 # 设置使用 http 代理
	postBuffer = 1048576000 # 扩大缓冲区，约 1 GB
	maxRequestBuffer = 1048576000 # 扩大缓冲区，约 1 GB

名词解释：

autocrlf：配置 Git 自动处理（转换）行结束符的默认行为。参见：配置 Git 处理行结束符 - GitHub Docs[EB/OL]. [2026-03-26]. https://docs.github.com/zh/get-started/git-basics/configuring-git-to-handle-line-endings.
signingkey：指设置带签名提交时默认使用的签名密钥。signingkey 既可指 GPG Key，亦可指 SSH Key。自 Git 2.34 起，Git 支持了 SSH 签名验证功能。参见：关于提交签名验证 - GitHub Docs[EB/OL]. [2026-03-26]. https://docs.github.com/zh/authentication/managing-commit-signature-verification/about-commit-signature-verification.

拉取命令：

$ git clone https://github.com/FreeBSD-Ask/FreeBSD-Ask

附录：Windows Git 配置示例

[filter "lfs"]
	required = true
	clean = git-lfs clean -- %f
	smudge = git-lfs smudge -- %f
	process = git-lfs filter-process
[user]
	name = ykla
	email = [email protected]
	signingkey = 11B44C23A0A0B986
[commit]
  gpgsign = true
[core]
	autocrlf = true
	longpaths = true
	editor = 'C:/Program Files/Notepad++/notepad++.exe' -multiInst -nosession
[difftool "sourcetree"]
	cmd = "'' "
[mergetool "sourcetree"]
	cmd = "'' "
	trustExitCode = true
[http]
	proxy = http://localhost:7890
	postBuffer = 1048576000
	maxRequestBuffer = 1048576000

[gpg]
	program = C:/Program Files/GnuPG/bin/gpg.exe
[safe]
	directory = C:/Users/ykla/Documents/hub/unix-haters

故障排除

致命错误：无法访问 'https://github.com/FreeBSD-Ask/FreeBSD-Ask/': Recv failure: 连接被对方重置

请尝试拉取项目 https://github.com/FreeBSD-Ask/LDWG。

若报错类似，说明您的网络存在问题，请使用代理。

项目简介

本项目主要托管在 GitBook（即 https://book.bsdcn.org）；

https://docs.bsdcn.org 由社区自行构建，docs 网站本身的贡献指南参见：FreeBSD 从入门到跑路 VitePress 镜像项目[EB/OL]. [2026-03-26]. https://github.com/FreeBSD-Ask/FreeBSD-Ask.github.io/blob/main/README.md。

技巧
若您仅想贡献内容本身，尚无改进 docs 网站浏览体验与构建优化等意向，则仅需阅读本文即可。

项目结构概览

> FreeBSD-Ask-main
│  .gitattributes  # 用于让 GitHub 正确识别 markdown，用于在 GitHub 正确高亮，正确显示编程语言（Languages）的统计信息
│  .gitignore # 一些规则，用于阻止 git 上传特定类型的文件或目录，如 node_modules
│  CHANGELOG-ARCHIVE.md # 普通文件，记录既往所有重要变动
│  CHANGELOG.md # 普通文件，记录当前季度的重要变动。当你有新的子章节提交或彻底重写时，请将其记录到此处
│  CODE_OF_CONDUCT.md # 用于合规，行为准则
│  CONTRIBUTING.md # 贡献指南（本文本身）
│  LICENSE # 许可证
│  mu-lu.md # 由 GitHub Action mulu.yml 自动同步
│  README.md # 主页
│  SECURITY.md # 用于合规，安全报告策略
│  SUMMARY.md # 目录文件，同时用于生成 vitepress 左侧边栏
│
├─.gitbook # 图片目录
│  └─assets # 图片
│          1-install.png
│          1.png
│          1011.png
│          其他图片从略
│
├─.github  # Github Action 相关
│  │  .autocorrectrc # 由 AutoCorrect.yml 调用
│  │  .markdownlint.json # 由 markdown-lint2.yml 调用
│  │  auto_assign.yml # 由 Auto-Assign.yml 调用
│  │  dependabot.yml # 检查 GitHub Action 调用的 Action 有无更新，并提交 PR
│  │  lychee.toml # 由 links.yml 调用
│  │
│  ├─ISSUE_TEMPLATE  # GitHub issue、PR 模板
│  │      bug_report.md  # GitHub issue 模板
│  │      feature_request.md  # GitHub PR 模板
│  │
│  ├─scripts # GitHub Action 相关，由 yml 脚本调用
│  │      check_images.py # 由 check-images.yml 调用
│  │      update_ga4_readme.py # 由 update-ga4.yml 调用
│  │      update_progress.sh # 由 Update-commit-progress.yml 调用
│  │
│  └─workflows # GitHub Action，用于自动化处理一些简单任务
│          Auto-Assign.yml # 自动为 issue PR 分配人员进行处理
│          AutoCorrect.yml # markdown 格式修正，会自动提交 PR
│          check-images.yml # 检查图片的调用情况，有无正确引用图片，不正确会生成 issue
│          create-pdf.yml # 用于在 GitHub release 生成电子书 PDF、EPUB
│          file-name-check.yml # 检查 SUMMARY.md 目录中的文件引用是否正确，不正确会生成 issue
│          links.yml # 链接检查，检查文中调用的 URL 是否能正常访问
│          markdown-lint2.yml # markdown 格式检查
│          md-padding.yml # markdown 空格检查与修复
│          mulu.yml # 从 SUMMARY.md 生成的镜像文件
│          sync-headers.yml # 从 SUMMARY.md 更新所有 markdown 文件的一级标题。如果你要修改 `#` 标题，必须在此处进行修改，否则会被其覆盖
│          Update-commit-progress.yml # 进度检查工具，每 3533 次提交为一个版本，用于插入到 README.md
│          update-ga4.yml # 谷歌统计数据，用于插入到 README.md
│
├─.vitepress # vitepress 相关，详见 FreeBSD-Ask/FreeBSD-Ask.github.io
│  │  config.mts
│  │
│  └─theme # vitepress 相关，详见 FreeBSD-Ask/FreeBSD-Ask.github.io
│          custom.css
│          index.js
│          Layout.vue
│
├─di-1-zhang-zou-jin-freebsd # 第 1 章的章节目录
│      di-1.1-unix.md # 第 1 章的文件
│      di-1.2-dao-lun.md
│      di-1.3-jie-freebsd-jian-shi.md
│      di-1.4-Fiat-Lux.md
│
├─di-10-zhang-vpn-yu-dai-li # 第 10 章的章节目录
│      di-10.1-jie-http-dai-li.md # 第 10 章的文件
│      di-10.2-jie-v2ray.md
│      di-10.3-jie-clash.md
│      di-10.4-jie-openvpn.md
│
└─其他目录和文件从略
│
├─public # vitepress 相关，参见 FreeBSD-Ask/FreeBSD-Ask.github.io
│      favicon.ico
│      logo.svg
│
└─其他目录和文件从略

如何新建章节

自行操作时参见操作实例 Commit 6023cc8[EB/OL]. [2026-03-26]. https://github.com/FreeBSD-Ask/FreeBSD-Ask/commit/6023cc8d58f3a1b9849ff11fa63bf3980177c370 和下方 SUMMARY.md 结构说明。

若有困难可发邮件联系 ykla 协助操作。

`SUMMARY.md` 目录结构

# Table of contents

* [FreeBSD 从入门到跑路](README.md)
* [编辑日志](CHANGELOG.md)
* [贡献指南与开放任务](CONTRIBUTING.md)
* [目录](mu-lu.md)

## 前言

* [前言](qian-yan/qian-yan.md)
* [致读者](qian-yan/zhi-du-zhe.md)
* [致谢](qian-yan/zhi-xie.md)
* [绪论](qian-yan/xu-lun.md)

## 第 1 章 FreeBSD 初见

* [1.1 操作系统的历程：UNIX、BSD 和 Linux](di-1-zhang-zou-jin-freebsd/di-1.1-unix.md)
* [1.2 FreeBSD 导论](di-1-zhang-zou-jin-freebsd/di-1.2-dao-lun.md)
* [1.3 George Berkeley（乔治·贝克莱）与 BSD 命名的文化背景](di-1-zhang-zou-jin-freebsd/di-1.3-jie-freebsd-jian-shi.md)
* [1.4 加州大学伯克利分校和“Fiat Lux”（要有光）](di-1-zhang-zou-jin-freebsd/di-1.4-Fiat-Lux.md)

## 第 2 章 安装 FreeBSD

* [2.1 安装前的准备工作](di-2-zhang-an-zhuang-freebsd/di-2.1-install-pre.md)
* [2.2 使用 bsdinstall 开始安装](di-2-zhang-an-zhuang-freebsd/di-2.2-jie-start-install.md)
* [2.3 键盘布局和主机名](di-2-zhang-an-zhuang-freebsd/di-2.3-jie-use-bsdinstall.md)
* [2.4 选择安装组件](di-2-zhang-an-zhuang-freebsd/di-2.4-jie-select.md)
* [2.5 分配磁盘空间](di-2-zhang-an-zhuang-freebsd/di-2.5-jie-fen-pei-disk.md)
* [2.6 设置 root 密码](di-2-zhang-an-zhuang-freebsd/di-2.6-root-jie.md)
* [2.7 网络设置](di-2-zhang-an-zhuang-freebsd/di-2.7-jie-net.md)
* [2.8 时区、服务、安全、固件和账户](di-2-zhang-an-zhuang-freebsd/di-2.8-jie-more.md)
* [2.9 完成安装](di-2-zhang-an-zhuang-freebsd/di-2.9-end-jie.md)
* [2.10 故障排除](di-2-zhang-an-zhuang-freebsd/di-2.10-jie-eol.md)
* [2.11 将 U 盘启动盘恢复为普通 U 盘（基于 Windows）](di-2-zhang-an-zhuang-freebsd/di-2.11-jie-usb.md)

其他从略

可以看到，SUMMARY.md 在形式上就是普通的 Markdown 文档，并无特殊支持。

但有一些注意事项：

第一行 # Table of contents 绝对不允许变更，否则 GitBook 将无法识别，导致失去同步。
要求格式应为 * [2.2 使用 bsdinstall 开始安装](di-2-zhang-an-zhuang-freebsd/di-2.2-jie-start-install.md)，不允许出现 * [2.2 使用 bsdinstall 开始安装](di-3-zhang-ni-hao/di-2.2-jie-start-install.md) 这种情况，即目录结构与文件放置位置必须一致（不一致虽不会报错，但本项目要求保持一致）。
通过 sync-headers.yml，将自动同步 SUMMARY.md 中的章节标题到具体的 Markdown 文件中。因此若需修改 di-2.2-jie-start-install.md 的一级标题 # 2.2 使用 bsdinstall 开始安装，必须仅修改 SUMMARY.md 中的 2.2 使用 bsdinstall 开始安装，否则会被 sync-headers.yml 覆盖。当二者不一致时，若提交时未触发脚本构建，则 GitBook 将以 SUMMARY.md 中的目录为准。

预览页面

当您提交 PR 时，系统会自动生成一个预览网站。

实际上，所有提交都有对应的网站版本：

您可通过该链接获取当前 PR 的实际显示样式：

且每次 push 都会自动更新：

开放任务

所有任务的排序均为随机，无优先级之分，您可选择感兴趣的任务进行。

开源社区

维护百度百科、维基百科相关条目

如增补修订各 BSD 中文条目。

帮助修订 USTC 镜像脚本

FreeBSD ToDo

不再需要 的内容（请不要撰写下列条目）：

Just for fun（可有可无）

20.7.创建和使用软盘（谁还有这种东西？2024，日本政府决定全面淘汰软盘）（无意义，但勉强可以写，若有光驱和软盘 Just for fun）
20.6.创建和使用 DVD（无意义，但勉强可以写，若有光驱和光盘 Just for fun）
20.5.创建和使用 CD（无意义，但勉强可以写，若有光驱和光盘 Just for fun）
16.9.Kerberos（谁在用？）

需要重写 的内容（请撰写这些内容）：

参见：Projects[EB/OL]. [2026-03-26]. https://github.com/FreeBSD-Ask/FreeBSD-Ask/projects。

NetBSD ToDo

参见：Projects[EB/OL]. [2026-03-26]. https://github.com/FreeBSD-Ask/FreeBSD-Ask/projects。

DragonFlyBSD ToDo

参见：Projects[EB/OL]. [2026-03-26]. https://github.com/FreeBSD-Ask/FreeBSD-Ask/projects。

上一页UEFI/BIOS 注解（AMI BIOS）下一页UEFI/BIOS 概述与警告

最后更新于 22天前

晚上好

hashtag为什么不去建设《FreeBSD 手册》

hashtag贡献指南概述

hashtag基本原则与方法论

hashtag基本原则

hashtag使之成为“一本书”，而不仅是字典或手册

hashtag细则

hashtag实用附录

hashtag如何使用 Git 拉取本项目

hashtag附录：Windows Git 配置示例

hashtag故障排除

hashtag项目简介

hashtag项目结构概览

hashtag如何新建章节

hashtagSUMMARY.md 目录结构

hashtag预览页面

hashtag开放任务

hashtag开源社区

hashtag维护百度百科、维基百科相关条目

hashtag帮助修订 USTC 镜像脚本

hashtagFreeBSD ToDo

hashtagNetBSD ToDo

hashtagDragonFlyBSD ToDo

为什么不去建设《FreeBSD 手册》

贡献指南概述

基本原则与方法论

基本原则

使之成为“一本书”，而不仅是字典或手册

细则

实用附录

如何使用 Git 拉取本项目

附录：Windows Git 配置示例

故障排除

项目简介

项目结构概览

如何新建章节

`SUMMARY.md` 目录结构

预览页面

开放任务

开源社区

维护百度百科、维基百科相关条目

帮助修订 USTC 镜像脚本

FreeBSD ToDo

NetBSD ToDo

DragonFlyBSD ToDo