Incus 方法

信息

虽然此方法仍然适用于 LXD，但作者更倾向于使用 Incus。原因是从开发角度来看，Incus 在 LXD 之前就已推出，这包括可用的镜像。截至 2025 年 9 月，Incus 提供了 Rocky Linux 10 和其他 RHEL 重建版 10 的镜像。而 LXD 镜像目前仅包含 9 个构建。这可能是由于 Linux Containers 项目负责人 Stéphane Graber 在 2023 年 12 月宣布的许可变更。

此外，本过程仍然适用于当前版本的文档。如果文档是在任何版本分支（main、rocky-9 和 rocky-8）上创建或编辑的，则同步到容器的文档将显示正确的内容。这意味着您可以按原样继续使用此过程。其中包含一些关于版本的重要附加说明。

技巧

如果您将 Rocky Linux 10 作为您的工作站，您需要记住，在重写本文档时，lsyncd 无法从 EPEL 获取。您需要使用从源代码安装的方法。

简介¶

有几种方法可以运行 mkdocs 的副本，以确切了解您的 Rocky Linux 文档在合并到实时系统时将如何显示。本特定文档涉及在本地工作站上使用 incus 容器，将 mkdocs 中的 Python 代码与其他可能正在处理的项目分开。

建议将项目分开，以避免引起工作站代码问题。

先决条件和假设¶

熟悉并舒适使用命令行
熟悉使用编辑、SSH 和同步工具，或愿意跟随学习
Incus 参考 - 这里有一个关于在服务器上构建和使用 incus 的长文档，但您只需要在 Linux 工作站上进行基本安装。
使用 lsyncd 进行文件镜像。请参阅此处关于此的文档。
您将需要使用此文档为您的用户和本地工作站上的“root”用户生成公钥。
在我们的示例中，我们的桥接接口运行在 10.56.233.1 上，我们的容器运行在 10.56.233.189 上。但是，您的桥接和容器的 IP 将不同。
本文档中的“youruser”代表您的用户 ID。
假设您已经在工作站上克隆了文档仓库，并正在进行文档开发。

The `mkdocs` container¶

Create the container¶

我们的第一步是创建 incus 容器。在这里使用容器的默认设置（桥接接口）即可。

我们将为 mkdocs 在我们的工作站上添加一个 Rocky 容器。只需将其命名为“mkdocs”。

incus launch images:rockylinux/10 mkdocs

容器需要成为代理。默认情况下，当 mkdocs serve 启动时，它运行在 127.0.0.1:8000 上。当它在本地工作站上且没有容器时，这是可以的。但是，当它在本地工作站的 incus 容器内时，您需要设置容器的代理端口。执行此操作：

incus config device add mkdocs mkdocsport proxy listen=tcp:0.0.0.0:8000 connect=tcp:127.0.0.1:8000

在上面的行中，“mkdocs”是我们的容器名称，“mkdocsport”是您为代理端口指定的任意名称，类型是“proxy”，您正在侦听所有 TCP 接口的 8000 端口，并连接到该容器的本地主机上的 8000 端口。

注意

如果您正在网络上的另一台机器上运行 incus 实例，请记住确保防火墙中已打开 8000 端口。

安装包¶

首先，使用以下命令进入容器：

incus shell mkdocs bash

对于 Rocky Linux 10，您需要一些软件包：

dnf install git openssh-server python3-pip rsync

安装完成后，您需要启用并启动 sshd：

systemctl enable --now sshd

Container users¶

您需要为我们的 root 用户设置密码，然后将我们的用户（您在本地机器上使用的用户）添加到 sudoers 列表中。目前您是“root”用户。要更改密码，请输入：

passwd

设置一个安全且易于记忆的密码。

接下来，添加您的用户并设置密码：

adduser youruser
passwd youruser

将您的用户添加到 sudoers 组：

usermod -aG wheel youruser

您应该能够从工作站使用 root 用户或您的用户 SSH 进入容器并输入密码。在继续之前，请确保您可以做到这一点。

SSH for root and your user¶

在此过程中，root 用户（至少）需要能够无密码 SSH 进入容器。这是因为您将要实现 lsyncd 进程。这里的假设是您可以在本地工作站上使用 sudo 切换到 root 用户。

sudo -s

假设 root 用户在 ./ssh 目录中已有一个 id_rsa.pub 密钥。如果没有，请使用此过程生成一个。

ls -al .ssh/
drwx------  2 root root 4096 Feb 25 08:06 .
drwx------ 14 root root 4096 Feb 25 08:10 ..
-rw-------  1 root root 2610 Feb 14  2021 id_rsa
-rw-r--r--  1 root root  572 Feb 14  2021 id_rsa.pub
-rw-r--r--  1 root root  222 Feb 25 08:06 known_hosts

要实现容器的 SSH 访问而不必输入密码，前提是 id_rsa.pub 密钥存在，只需运行：

ssh-copy-id root@10.56.233.189

然而，对于您的用户，您需要将整个 .ssh/ 目录复制到您的容器。您将为该用户保留所有内容，以便您访问 GitHub 的 SSH 方式保持不变。

要将所有内容复制到您的容器，您只需要以您的用户身份执行此操作，**而不是**使用 sudo：

scp -r .ssh/ youruser@10.56.233.189:/home/youruser/

接下来，以您的用户身份 SSH 进入容器：

ssh -l youruser 10.56.233.189

您需要确保一切都相同。您将使用 ssh-add 来做到这一点。您还必须确保 ssh-agent 可用。

eval "$(ssh-agent)"
ssh-add

Cloning repositories¶

您需要克隆两个仓库，但不需要添加任何 git 远程。这里的文档仓库将仅显示当前文档（从您的工作站镜像）和 docs。

rockylinux.org 仓库用于运行 mkdocs serve，并将使用镜像作为其源。请以您的非 root 用户身份运行所有这些步骤。如果您无法以您的用户 ID 克隆仓库，那么就说明您的身份在 git 方面存在**问题**，您需要重新检查前面的几个步骤以重新创建您的密钥环境（上方）。

首先，克隆文档：

git clone git@github.com:rocky-linux/documentation.git

接下来，克隆 docs.rockylinux.org：

git clone git@github.com:rocky-linux/docs.rockylinux.org.git

如果出现错误，请返回到前面的步骤，并确保它们都正确无误后再继续。

Setting up `mkdocs`¶

所需的插件安装全部使用 pip3 和 docs.rockylinux.org 目录中的“requirements.txt”文件完成。虽然此过程会因为您使用 root 用户向系统目录写入更改而出现争执，但您必须以 root 用户身份运行。

您在这里使用 sudo 来执行此操作。

进入目录：

cd docs.rockylinux.org

然后运行

sudo pip3 install -r requirements.txt

接下来，您必须使用一个额外的目录来设置 mkdocs。 mkdocs 需要创建 docs 目录，然后在它下面链接 documentation/docs 目录。执行此操作：

mkdir docs
cd docs
ln -s ../../documentation/docs

Testing `mkdocs`¶

现在您已经设置好了 mkdocs，请尝试启动服务器。请记住，此过程会争辩说它看起来像生产环境。它不是，所以请忽略警告。使用以下命令启动 mkdocs serve：

mkdocs serve -a 0.0.0.0:8000

您将在控制台中看到此内容或类似内容：

INFO     -  Building documentation...
WARNING  -  Config value: 'dev_addr'. Warning: The use of the IP address '0.0.0.0' suggests a production environment or the use of a
            proxy to connect to the MkDocs server. However, the MkDocs' server is intended for local development purposes only. Please
            use a third party production-ready server instead.
INFO     -  Adding 'sv' to the 'plugins.search.lang' option
INFO     -  Adding 'it' to the 'plugins.search.lang' option
INFO     -  Adding 'es' to the 'plugins.search.lang' option
INFO     -  Adding 'ja' to the 'plugins.search.lang' option
INFO     -  Adding 'fr' to the 'plugins.search.lang' option
INFO     -  Adding 'pt' to the 'plugins.search.lang' option
WARNING  -  Language 'zh' is not supported by lunr.js, not setting it in the 'plugins.search.lang' option
INFO     -  Adding 'de' to the 'plugins.search.lang' option
INFO     -  Building en documentation
INFO     -  Building de documentation
INFO     -  Building fr documentation
INFO     -  Building es documentation
INFO     -  Building it documentation
INFO     -  Building ja documentation
INFO     -  Building zh documentation
INFO     -  Building sv documentation
INFO     -  Building pt documentation
INFO     -  [14:12:56] Reloading browsers

如果一切都正确，您应该能够打开网页浏览器，访问您的容器 IP 上的 :8000 端口，并看到文档站点。

在我们的示例中，在浏览器地址栏输入以下内容（**注意**：为避免 URL 损坏，“your-server-ip”表示您自己的服务器 IP，您只需替换为您自己的 IP）：

http://your-server-ip:8000

`lsyncd`¶

如果您在网页浏览器中看到了文档，那么您就快完成了。最后一步是使容器中的文档与本地工作站上的文档保持同步。

如前所述，您在此处使用 lsyncd 来完成此操作。

lsyncd 的安装因 Linux 版本而异。本文档涵盖了在 Rocky Linux 上从 EPEL（企业 Linux 的额外软件包）安装 RPM 以及从源代码安装的方法。如果您使用的是其他 Linux 类型（例如 Ubuntu），它们通常有自己的软件包，但存在细微差别。

例如，Ubuntu 的配置文件名称不同。如果您使用的是 Rocky Linux 以外的其他 Linux 工作站类型，并且不想从源代码安装，那么很可能您的平台有可用的软件包。

目前，我们假设您使用的是 Rocky Linux 工作站，并且正在使用随附文档中的 RPM 安装方法。

注意

截至本文撰写之时，lsyncd 无法从 Rocky Linux 10 的 EPEL 获取。如果您的工作站版本是这样，您需要使用源代码安装方法。

配置¶

注意

root 用户必须运行守护进程，因此在创建配置文件和日志时您必须是 root 用户。此处我们假定使用 sudo -s。

您需要有一些日志供 lsyncd 写入：

touch /var/log/lsyncd-status.log
touch /var/log/lsyncd.log

您还需要创建一个排除文件，即使在这种情况下您不排除任何内容：

touch /etc/lsyncd.exclude

最后，您需要创建配置文件。在此示例中，我们使用 vi 作为编辑器，但请使用您熟悉的编辑器。

vi /etc/lsyncd.conf

然后将此内容放入该文件中并保存。请务必将“youruser”替换为您的实际用户，并将 IP 地址替换为您自己的容器 IP。

settings {
   logfile = "/var/log/lsyncd.log",
   statusFile = "/var/log/lsyncd-status.log",
   statusInterval = 20,
   maxProcesses = 1
   }

sync {
   default.rsyncssh,
   source="/home/youruser/documentation",
   host="root@10.56.233.189",
   excludeFrom="/etc/lsyncd.exclude",
   targetdir="/home/youruser/documentation",
   rsync = {
     archive = true,
     compress = false,
     whole_file = false
   },
   ssh = {
     port = 22
   }
}

假设您在安装 lsyncd 时启用了它，此时您只需启动或重启该进程：

systemctl restart lsyncd

为确保一切正常，请检查日志，特别是 lsyncd.log，如果一切都已正确启动，它应该会显示类似以下内容：

Fri Feb 25 08:10:16 2022 Normal: --- Startup, daemonizing ---
Fri Feb 25 08:10:16 2022 Normal: recursive startup rsync: /home/youruser/documentation/ -> root@10.56.233.189:/home/youruser/documentation/
Fri Feb 25 08:10:41 2022 Normal: Startup of "/home/youruser/documentation/" finished: 0
Fri Feb 25 08:15:14 2022 Normal: Calling rsync with filter-list of new/modified files/dirs

Versioning notes¶

您需要从Rocky Linux 文档仓库克隆文档仓库。这一点很重要，因为如果您克隆了自己的仓库副本，则无法 git checkout rocky-8 和 rocky-9 分支。只有 main 分支可用。

GitHub workstation setup¶

这些步骤不是针对您的容器，而是针对您工作站上的文档副本。

克隆 Rocky Linux 文档仓库：

git clone git@github.com:rocky-linux/documentation.git

git remote 的名称将是“upstream”，而不是“origin”。使用以下命令检查远程名称：

git remote -v

克隆后立即，这将显示：

origin git@github.com:rocky-linux/documentation.git (fetch)
origin git@github.com:rocky-linux/documentation.git (push)

使用以下命令重命名远程：

git remote rename origin upstream

再次运行 git remote -v，您将看到：

upstream git@github.com:rocky-linux/documentation.git (fetch)
upstream git@github.com:rocky-linux/documentation.git (push)

将您的 fork 添加为名为“origin”的远程。替换为您实际的 GitHub 用户名：

git remote add origin git@github.com:[your-github-user-name]/documentation.git

再次运行 git remote -v，您将看到：

origin git@github.com:[your-github-user-name]/documentation.git (fetch)
origin git@github.com:[your-github-user-name]/documentation.git (push)
upstream git@github.com:rocky-linux/documentation.git (fetch)
upstream git@github.com:rocky-linux/documentation.git (push)

您需要用版本分支（除了 main）填充您的 fork。main 分支当前包含 10 版信息。您需要用 rocky-8 和 rocky-9 分支填充您的 fork，以便准备编辑旧版本中的文档。第一步是 git checkout 这些分支名称：
```
git checkout rocky-8
```
第一次执行此操作时，您会看到：
```
branch 'rocky-8' set up to track 'upstream/rocky-8'.
Switched to a new branch 'rocky-8'
```
接下来，将分支推送到您的 fork：
```
git push origin rocky-8
```
这看起来像是创建了一个新的拉取请求，但当您检查您的 fork 分支内容时，您会看到 rocky-8 现在是分支之一。

对 rocky-9 分支重复这些步骤。

How this applies to this procedure¶

创建了分支后，如果您只想为 rocky-9 编辑 README.md，您需要基于 rocky-9 版本分支创建一个新分支：

git checkout -b fixes_for_rocky9_readme rocky-9

然后正常编辑文档。当您保存工作时，您的容器文档将更新，并且按照本文档的描述运行 mkdocs serve 将会显示该内容。

完成后，并将更改推送到您的 fork 以创建拉取请求，您可以再次切换回 main 分支。由于您的所有工作都在已签出的 rocky-9 分支内，您容器中同步的文档将恢复到您开始进程之前的状态。通过这种方式，无论您处理哪个版本，都可以始终跟踪您的工作。您的容器将与您的本地工作站内容保持同步。

结论¶

您可以在工作站上处理文档，同时在容器中的同步副本中看到更改。推荐的做法是所有 Python 都必须独立于您可能正在开发的任何其他 Python 代码运行。使用 incus 容器可以更轻松地实现这一点。

作者：Steven Spencer

贡献者：Ezequiel Bruni, Ganna Zhyrnova