这是一段机器翻译的文本，可能包含错误！
良好的文档是区分记住事物如何运作以及在周日晚上 11 点卡住，因为服务器宕机且没有人记得如何设置它的关键。文档可能不是 IT 运维中最令人兴奋的部分，但它是最重要的部分之一。
为什么需要文档？
| 理由 | 说明 |
|---|---|
| 记忆 | 你六个月后不会记住所有事情，你也不需要记住 |
| 协作 | 其他人需要能够理解你所做的事情，而无需询问你 |
| 故障排除 | 当出现问题时，了解什么是正常的至关重要 |
| 重建 | 如果服务器崩溃，你需要知道它最初是如何配置的 |
| 可追溯性 | 发生了什么变化，何时以及由谁？ |
Skriv dokumentasjonen for “fremtidig deg”
最佳经验法则是：像向六个月后的自己解释一样写作。 这样可以保证你包含足够的信息，而不会使事情变得过于复杂。
IT 运维中的文档类型
Dokumentasjon er en kritisk del av IT-drift. God dokumentasjon sikrer at systemer kan driftes, vedlikeholdes og videreutvikles på en effektiv måte. Uten tilstrekkelig dokumentasjon kan feilsøking bli vanskelig og tidkrevende, og risikoen for driftsstans øker. Det finnes flere typer dokumentasjon som er relevant for IT-drift:
- Brukerdokumentasjon: Beskriver hvordan sluttbrukere skal bruke systemet.
- Systemdokumentasjon: Beskriver systemets arkitektur, funksjonalitet og tekniske detaljer.
- Driftsdokumentasjon: Beskriver hvordan systemet skal driftes, inkludert oppstart, nedstengning, overvåking og feilsøking.
- Vedlikeholdsdokumentasjon: Beskriver hvordan systemet skal vedlikeholdes, inkludert oppdateringer, patching og sikkerhetskopiering.
God dokumentasjon bør være:
- Oppdatert: Dokumentasjonen må holdes oppdatert i takt med endringer i systemet.
- Klar og konsis: Dokumentasjonen bør være lett å forstå og unngå unødvendig jargon.
- Tilgjengelig: Dokumentasjonen må være lett tilgjengelig for de som trenger den.
- Søkbar: Det må være enkelt å finne relevant informasjon i dokumentasjonen.
文档是 IT 运维的关键部分。良好的文档能够确保系统以有效的方式进行运营、维护和进一步开发。如果没有充分的文档，故障排除可能会变得困难且耗时，停机风险会增加。有几种类型的文档与 IT 运维相关：
- 用户文档： 描述了最终用户如何使用系统。
- 系统文档： 描述了系统的架构、功能和技术细节。
- 运维文档： 描述了如何运行系统，包括启动、关闭、监控和故障排除。
- 维护文档： 描述了如何维护系统，包括更新、补丁和备份。
良好的文档应该：
- 更新： 文档必须与系统的变化同步更新。
- 清晰简洁： 文档应该易于理解，避免不必要的术语。
- 可访问： 文档必须易于供需要它的人访问。
- 可搜索： 应该很容易在文档中找到相关信息。
网络拓扑图
网络拓扑图显示网络的物理和/或逻辑结构。它可以是从简单的草图到包含VLAN、IP地址和防火墙规则的详细图表。
一个好的网络拓扑图应该包含：
- 所有网络设备（交换机、路由器、防火墙、接入点）
- VLAN结构与子网
- 重要设备的IP地址（服务器、网关）
- 设备之间的连接
IP计划
IP计划是网络中IP地址分配的概述。它可以帮助您保持井然有序并避免冲突（两个设备使用相同地址）。
示例：
| VLAN | 名称 | 子网 | 网关 | DHCP范围 | 备注 |
|---|---|---|---|---|---|
| 10 | 管理 | 10.0.10.0/24 | 10.0.10.1 | .100 - .200 | 限制访问 |
| 20 | 员工 | 10.0.20.0/24 | 10.0.20.1 | .100 - .250 | |
| 30 | 学生 | 10.0.30.0/24 | 10.0.30.1 | .100 - .250 | 仅限互联网 |
| 50 | 服务器 | 10.0.50.0/24 | 10.0.50.1 | 无 (静态) | 静态IP地址 |
静态地址：
| IP地址 | 设备 | 角色 |
|---|---|---|
10.0.50.10 | web-01 | Nginx |
10.0.50.11 | db-01 | PostgreSQL |
10.0.50.12 | monitoring-01 | Grafana + Loki |
10.0.50.20 | proxmox | Hypervisor |
检查清单
检查清单确保不会遗漏任何内容。它们对于您不常执行的任务特别有用，例如设置新服务器或进行安全审查。
示例：新 Linux 服务器检查清单：
- 安装操作系统 (Debian/Ubuntu)
- 更新所有软件包 (
sudo apt update && sudo apt upgrade) - 创建具有 sudo 访问权限的用户
- 禁用通过 SSH 的 root 登录
- 配置防火墙 (
ufw) - 安装必要的软件
- 设置备份
- 在 IP 计划中记录服务器
- 测试服务是否正常工作
变更文档
每次您对生产环境（服务器、网络、服务）进行更改时，都应记录下来。 简单的日志就足够了：
## Endringslogg
### 2026-04-14 - Oppgradert Nginx
- **Hva:** Oppdatert Nginx fra 1.24 til 1.26
- **Hvorfor:** 安全更新 (CVE-2025-XXXX)
- **Hvem:** Ola
- **Resultat:** OK, ingen nedetid
### 2026-04-10 - Nytt VLAN for IoT
- **Hva:** Opprettet VLAN 40 for IoT-enheter
- **Hvorfor:** 将物联网设备与网络隔离
- **Hvem:** Kari
- **Resultat:** OK, alle printere flyttet til VLAN 40
Bruk Git!
如果您使用 Markdown 文件编写文档（推荐），您可以使用 Git 进行版本控制。 这样您就可以自动记录所有更改的历史记录，并查看谁在何时更改了什么。
运营文档
运营文档描述了系统当前状态下的运作方式：
| 什么 | 示例 |
|---|---|
| 系统架构 | “我们运行 Proxmox，拥有 3 个虚拟机：web、db、监控” |
| 访问信息 | “通过端口 22 进行 SSH 访问，仅从 VPN” |
| 备份例程 | “每天凌晨 02:00 备份到外部磁盘” |
| 联系方式 | “出现问题时，请联系 Ola (admin)” |
| 恢复步骤 | “使用以下命令重启：sudo systemctl restart nginx” |
文档工具
| 工具 | 用途 | 优点 |
|---|---|---|
| Markdown | 具有简单格式的文本 | 轻量级、可移植、可与 Git 配合使用 |
| draw.io | 图表和网络图 | 免费、可视化、导出为图片 |
| Obsidian | 使用 Markdown 和链接的笔记应用程序 | 适合个人知识库 |
| MkDocs | 将 Markdown 发布为网站 | 专业文档 |
| Git/GitHub | 文档的版本控制 | 历史记录、协作、备份 |
任务 1 - 创建一个简单的网络图
使用 draw.io (免费) 绘制您在家或学校的网络：
- 从互联网连接和路由器开始
- 添加交换机和接入点
- 绘制服务器、PC 和其他设备
- 在您知道的情况下写上 IP 地址
不必完美。重点是开始以视觉方式思考网络。
任务 2 - 创建你自己的检查清单
考虑一下你经常用 IT 完成的事情（例如设置新的虚拟机、安装开发机器或配置 VS Code）。为这个过程编写一个检查清单：
- 所有步骤是什么？
- 你最常忘记什么？
- 你能简化一些步骤吗？
将其保存为 Markdown 文档，以便下次使用。
任务 3 - 记录你的其中一项服务
选择你设置的一项服务（虚拟机、Docker 容器、Web 服务器），并编写一份简短的运维文档：
- 该服务做什么？
- 如何启动/停止它？
- IP 地址和端口是什么？
- 是否有备份？
用 Markdown 编写并将其放入 Git 仓库。
总结
- 为未来的你编写文档：像向一无所知的人解释一样写作
- **网络图**和**IP计划**提供基础设施概览
- **检查清单**确保在重复任务中不会遗漏任何内容
- **变更日志**跟踪做了什么、何时以及由谁完成
- **操作文档**描述了系统当前的工作方式
- 使用 Markdown + Git 实现简单、版本控制的文档