简介¶

信息

此处的步骤适用于 Incus 和 LXD。

有几种方法可以运行 mkdocs 的副本，以查看您的 Rocky Linux 文档在实时系统上合并后的确切外观。本特定文档讨论了在您的本地工作站上使用 LXD 容器，以将 mkdocs 中的 Python 代码与您可能正在处理的其他项目分开。

建议将项目分开以避免给工作站的代码造成问题。

这也是本文档的配套文档：此处提供的 Docker 版本。

先决条件和假设¶

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

`mkdocs` 容器¶

创建容器¶

我们的第一步是创建 LXD 容器。在这里，使用容器的默认值（桥接接口）就可以了。

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

lxc launch images:rockylinux/8 mkdocs

容器需要是一个代理。默认情况下，当 mkdocs serve 启动时，它在 127.0.0.1:8000 上运行。在没有容器的本地工作站上，这很好。但是，当它在您本地工作站上的 LXD **容器** 中运行时，您需要使用代理端口设置容器。使用以下命令执行此操作：

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

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

注意

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

安装软件包¶

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

lxc exec mkdocs bash

requirements.txt 中针对 8.x 的更改

当前 requirements.txt 将需要比 Rocky Linux 8.5 或 8.6 中默认安装的版本更新的 Python 版本。为了能够安装所有其他依赖项，请执行以下操作：

sudo dnf module enable python38
sudo dnf install python38

如果您使用的是 Rocky Linux 8.x，请使用以下命令安装软件包：

dnf install git openssh-server rsync

**不要**安装 python3-pip

对于 Rocky Linux 9.x，您将需要一些软件包（有关 8.x 软件包安装，请参阅“requirements.txt 中针对 8.x 的更改”！）

dnf install git openssh-server python3-pip rsync

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

systemctl enable --now sshd

容器用户¶

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

passwd

设置一个安全且难忘的密码。

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

adduser youruser
passwd youruser

将您的用户添加到 sudoers 组

usermod -aG wheel youruser

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

root 用户和您的用户的 SSH¶

在本步骤中，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/ 目录复制到容器中。您将为该用户保留所有内容不变，这样我们通过 SSH 访问 GitHub 的方式就保持一致。

要将所有内容复制到容器中，您只需以用户身份执行此操作，**不要** 使用 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

克隆仓库¶

您需要克隆两个仓库，但无需添加任何 git 远程仓库。此处的文档仓库仅显示当前文档（从您的工作站镜像），以及文档。

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

如果您遇到错误，请返回到上面的步骤，并确保所有步骤都正确，然后再继续。

设置 `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

测试 `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，此处将 IP 地址更改为 "your-server-ip"。您只需要将 IP 地址替换即可）

http://your-server-ip:8000

`lsyncd`¶

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

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

lsyncd 的安装方式取决于您的 Linux 版本。本文档介绍了在 Rocky Linux 上以及从源代码安装它的方法。如果您使用的是其他类型的 Linux（例如 Ubuntu），它们通常有自己的软件包，但它们有细微差别。

例如，Ubuntu 将配置文件命名为不同的名称。请注意，如果您使用的是除了 Rocky Linux 之外的其他类型的 Linux 工作站，并且不想从源代码安装，那么您的平台可能提供了软件包。

目前，我们假设您使用的是 Rocky Linux 工作站，并使用包含文档中的 RPM 安装方法。

配置¶

注意

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

结论¶

现在，当您在工作站上处理文档时，无论是 git pull 还是创建分支来编写文档（像这样！），您都会看到更改出现在容器中的文档中，并且 mkdocs serve 会在网页浏览器中显示内容。

推荐的做法是将所有 Python 代码与您可能正在开发的任何其他 Python 代码分开运行。LXD 容器可以简化此操作。尝试使用这种方法，看看它是否对您有效。

作者：Steven Spencer

贡献者：Ezequiel Bruni、Ganna Zhyrnova

简介¶