您如何避免服务器文档与实际设置不同步？

Question

我们为我们的环境提供了相当不错的文档（以 AsciiDoc 格式），最近允许另一个人在不到 30 分钟的时间内从头开始重新创建整个设置。
但是，我注意到在初始设置后，很容易发生对系统进行的小改动（比如：inetd 被禁用，我的 IMAP 服务器在一个额外的端口上侦听 ManageSieve 连接，一个新的路由器被添加到 exim 配置中）不要'不会立即出现在文档中（如果有的话）。

我的想法是，以避免（部分？）这个问题产生的文档出来的配置文件，并在其中的意见-实现这个可能是把一个方式/etc和/usr/local/etc进入一些源代码管理系统（说- GIT），然后运行在每次提交时重新生成文档的脚本。但是，我不确定这是否是矫枉过正和/或难以正确处理（毕竟，我不想在我的文档中提供源文件的完整副本，而只想提供差异）。

其他人如何避免服务器文档过时 - 是否有一种自动保持同步的好方法，或者您是否只有在修改系统的同时更新文档的纪律？

Answer 1

如果您只管理一两个小型系统，那么设置像 puppet 或 Chef 这样的大型配置管理系统似乎有点过分。（不过，如果您计划将来拥有更多系统，请现在就开始！）

对于这样一个小设置，我建议使用类似etckeeper，程序这使/etc成一个git存储库，并提供了一些有用的功能，喜欢做，只要你安装，升级或删除软件包自动提交。

Answer 2

每次对系统进行更改时，您只需更新文档。又名Change Management。

大多数公司以如此荒谬的方式实施变更管理以使其变得比没有更糟糕的事实不应减损基本概念的效用或阻止您正确地做。

我曾经使用html或某种 wiki 来跟踪我的所有配置。现在我在 Windows 商店使用（不寒而栗）SharePoint，所以现在我使用我创建的 Word 文档“模板”来跟踪我拥有的每个系统和我所做的每个配置更改，这并不像听起来那么糟糕，因为有很多系统只是其他系统的千篇一律的副本，可以全部合并到同一个文档中。（并且我将我所有东西的本地副本保存在我的硬盘驱动器上，实际上以合理的方式组织起来，除了将它们扔到任何人的 SharePoint 站点的无组织堆上。）

最大的挑战是真正腾出时间来记录，我通过添加记录时间作为进行更改的时间的一部分来做到这一点。所以，其实没那么难，特别是如果你有点笨，并且不介意告诉人们搞砸并排队等候，因为你现在太忙了，他们的问题。

Answer 3

您永远不会摆脱某些文档，但正如您所暗示的，有些系统可以集成到您的变更过程中以涵盖其中的很多内容。

• 使用配置管理工具（如puppet或chef）。
• 以更改控制的方式存储您的配置。（如git或SVN）
• 确保配置是人类可读/可访问的（即纯文本、可搜索数据库）

通过将部署信息存储在配置项或代码中作为您进行更改的系统的一部分，通过这种方式，我们通常会错过（或不打扰）较低级别的文档。这也有一个额外的好处，即该过程在未来变得更加可重复。

外部文档仍然需要更新，但它变得非常高级，指向“deploy x”或“deploy y”而不是长命令/文件列表。这另外使文档更改既不频繁又更容易，这也意味着它更有可能完成。

同样在你回家之前，使用 puppet 可能已经有人写了一些东西来管理你想要的东西。