jonaspammer.apache2

// 此文件由 .github/workflows/gh-pages.yml 生成 - 所有本地更改最终将会丢失！
= ansible-role-apache2
Jonas Pammer <[email protected]>;
:toc: left
:toclevels: 2
:toc-placement!:
:source-highlighter: rouge


https://galaxy.ansible.com/jonaspammer/apache2[image:https://img.shields.io/badge/available%20on%20ansible%20galaxy-jonaspammer.apache2-brightgreen[在 Galaxy 上的版本]]
// 非常相关的状态徽章
https://github.com/JonasPammer/ansible-role-apache2/actions/workflows/ci.yml[image:https://github.com/JonasPammer/ansible-role-apache2/actions/workflows/ci.yml/badge.svg[测试 CI]]


一个用于安装 Apache2 的 Ansible 角色，包括启用/禁用模块、配置默认设置以及创建虚拟主机。


toc::[]

[[meta]]
== 🔎 元数据
以下是角色的相关信息…

* 所需的 Ansible 版本
* 支持的平台
* 角色的 https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html#role-dependencies[角色依赖关系]

.link:meta/main.yml[]
[source,yaml]
----
---
galaxy_info:
  role_name: "apache2"
  description:
    "用于安装 Apache2 的 Ansible 角色，启用/禁用模块，
    配置默认设置并创建虚拟主机。
    基于 geerlingguy 的 apache2 角色。"

  author: "jonaspammer"
  license: "MIT"

  min_ansible_version: "2.11"
  platforms:
    # 注意: "actively tested: " 后的文本表示 Docker 镜像名称
    - name: EL # (企业 Linux)
      versions:
        - "9" # 已积极测试: rockylinux9
    - name: Fedora
      versions:
        - "38" # 已积极测试: fedora38
        - "39" # 已积极测试: fedora39
    - name: Debian
      versions:
        - bullseye # 已积极测试: debian11
        - bookworm # 已积极测试: debian12
    - name: Ubuntu
      versions:
        - focal # 已积极测试: ubuntu2004
        - jammy # 已积极测试: ubuntu2204

  galaxy_tags:
    - web
    - apache
    - webserver
    - html
    - httpd

dependencies: []

allow_duplicates: true
----


[[requirements]]
== 📌 需求
// 任何本角色或 Ansible 本身未涵盖的先决条件应在此提及。
Ansible 使用者需要能够 `become`。

如果您使用 SSL/TLS (<<apache_vhosts_ssl>>)，您需要提供自己的证书和密钥文件。

如果您使用 Apache 和 PHP，我建议使用
https://github.com/geerlingguy/ansible-role-php/[geerlingguy.php] 角色
来安装 PHP，您可以使用 `mod_php`
（通过将正确的软件包，例如 Ubuntu 的 `libapache2-mod-php5`，添加到 `php_packages` 中），
或同时使用
https://github.com/geerlingguy/ansible-role-apache-php-fpm[`geerlingguy.apache-php-fpm` ]
通过 FPM 将 Apache 连接到 PHP。
请查阅链接角色的 README 以获取更具体的信息。

当目标为基于 Solaris 的系统时，
必须在 Ansible 控制器上安装 https://galaxy.ansible.com/community/general[`community.general` 集合]
（包含 `pkg5` 模块）。

当目标为基于 Suse 的系统时，
同样必须在 Ansible 控制器上安装 https://galaxy.ansible.com/community/general[`community.general` 集合]
（包含 `zypper` 模块）。


[[variables]]
== 📜 角色变量
// 应在此处描述可设置的变量以及可以/应该通过角色参数设置的任何变量。
// 任何来自其他角色和/或全局范围（例如 hostvars、group vars 等）的变量
// 也应在此处提及。

[source,yaml]
----
apache_mods_enabled:
  - rewrite
  - ssl
apache_mods_disabled: []
----
（仅适用于 Debian/RHEL）
要启用或禁用的 Apache 模块（这些将被链接到适当的位置）。
请查阅 <<apache__server_root_dir,apache 的根目录>> 中的 `mods-available`（Debian） / `conf.modules.d`（RHEL）目录，以获取所有可用模块。

[source,yaml]
----
apache_listen_ip: "*"
apache_listen_port: 80
apache_listen_port_ssl: 443
----
Apache 应该监听的 IP 地址和端口。
如果您有其他服务（例如反向代理）在 80 或 443 端口监听，
并需要更改默认值，这会很有用。

[source,yaml]
----
apache_remove_default_vhost: false
----
在 Debian/Ubuntu 中，Apache 的配置中包含一个默认虚拟主机。
将其设置为 `true` 以删除该默认值。

[source,yaml]
----
apache_state: started
----
设置 Apache 的初始状态。
推荐值: `started` 或 `stopped`

[source,yaml]
----
apache_enabled: true
----
设置 Apache 服务的初始状态。
推荐值: `true` 或 `false`

[source,yaml]
----
apache_restart_state: restarted
----
设置在进行配置更改时要使 Apache 处于的状态
（即在调用 `restart apache` 处理程序时）。
推荐值: `restarted` 或 `reloaded`

[[apache_default_favicon]]
[source,yaml]
----
apache_default_favicon: favicon.ico
----
要复制到服务器并由 Apache 用作默认图标的本地 Ansible 控制器上的文件路径。

=== 用于安装的角色变量

[source,yaml]
----
apache_packages: [操作系统特定，见 /defaults 目录]
----
要安装 Apache2 和大多数必需实用程序的软件包名称列表。

[source,yaml]
----
apache_packages_state: present
----
如果您启用了任何附加存储库，例如
https://launchpad.net/~ondrej/+archive/ubuntu/apache2[`ondrej/apache2`],
https://fedoraproject.org/wiki/EPEL[`EPEL`]，或
http://rpms.remirepo.net/[`remi`],
您可能希望有一种简单的方法来升级版本。
为了确保这一点，将其设置为 `latest`。

[source,yaml]
----
apache_enablerepo: ""
----
（仅适用于 RHEL/CentOS）
安装 Apache 时要使用的 https://docs.ansible.com/ansible/latest/collections/ansible/builtin/yum_module.html#parameter-enablerepo[存储库]。
如果您想要比操作系统核心存储库中可用的 Apache 的更新版本，
请使用诸如 https://fedoraproject.org/wiki/EPEL[EPEL] 的存储库
（可以使用 `repo-epel` 角色进行安装）。

=== 用于创建虚拟主机的角色变量

[TIP]
请查看 <<example_playbooks>> 部分以获取
产生的虚拟主机文件的示例格式。

[NOTE]
====
此角色通过运行
https://httpd.apache.org/docs/2.4/programs/httpd.html[对所有配置文件进行语法测试（`-t`）]
确保 Apache 配置有效，并在发生错误时还原生成的虚拟主机。
====

[source,yaml]
----
apache_create_vhosts: true
apache_vhosts_filename: "vhosts.conf"
apache_vhosts_template: "vhosts.conf.j2"
----
如果设置为 `true`，则创建一个由此角色的变量管理的虚拟主机文件（见下文），并放置在 Apache 配置文件夹中。
如果设置为 `false`，您可以将自己的虚拟主机文件放入 Apache 的配置文件夹中，并跳过此角色添加的方便（但更基础）虚拟主机文件。

您也可以覆盖所使用的模板，并设置路径到您自己的模板，
如果您需要进一步自定义虚拟主机的布局。

[source,yaml]
----
apache_global_vhost_settings: |
  DirectoryIndex index.php index.html
----
此变量在生成的虚拟主机文件中*不在任何 <VirtualHost> 指令内* 使用。

[WARNING]
=====
您在此更改的是应用于 Apache 的通用上下文的配置
（而不是更改应用于例如 `<VirtualHost>`/ `<Directory>`/... 的配置）。

理解此默认值的一点是
*`DirectoryIndex` 不会 _设置_ 而是 _附加_*
（这意味着我们不会撤消已做的其他配置），如其文档页面所述：

[quote,https://httpd.apache.org/docs/2.4/mod/mod_dir.html]
____
同一上下文内的多个 `DirectoryIndex` 指令将添加到
查找资源的列表中，而不是替换它。
____
=====

[source,yaml]
----
apache_vhosts:
  - servername: "local.dev"
    documentroot: "/var/www/html"
----
对于列表中的每个条目，
将生成一个 `<VirtualHost>` 指令，监听
`{{ apache_listen_ip }}:{{ apache_listen_port }}`。
   
列表中的每个条目可以具有以下属性
（请查阅 <<example_playbooks>> 部分获取示例。
请查阅官方文档链接页面以获取它们所代表的实际 Apache 指令的文档）。

`https://httpd.apache.org/docs/2.4/mod/core.html#servername[servername]`（必需）::

`https://httpd.apache.org/docs/2.4/mod/core.html#serveralias[serveralias]`::

`https://httpd.apache.org/docs/2.4/mod/core.html#serveradmin[serveradmin]`::

`https://httpd.apache.org/docs/2.4/mod/core.html#documentroot[documentroot]`::

`documentroot__link:https://httpd.apache.org/docs/2.4/mod/core.html#servername[allowoverride]`::
`AllowOverride` 指令用于 `DocumentRoot` 的 `<Directory>` 内。 +
默认为 `apache_vhosts_default_documentroot__allowoverride` 的值。

`documentroot__link:https://httpd.apache.org/docs/2.4/mod/core.html#options[options]`::
`Options` 指令用于 `DocumentRoot` 的 `<Directory>` 内。 +
默认为 `apache_vhosts_default_documentroot__options` 的值。

https://httpd.apache.org/docs/2.4/mod/mod_log_config.html#logformat[`logformat`]::

`https://httpd.apache.org/docs/2.4/mod/core.html#loglevel[loglevel]`::

[[apache_vhosts__errorlog]]
`https://httpd.apache.org/docs/2.4/mod/core.html#errorlog[errorlog]`::
可以是字符串（表示路径，不会自动加引号）或复杂数据类型：
+
====
`path`:: 
路径。
会用 `"` 引号包含。

`extra`::
附加字符串，附加在 `path` 之后。

`extra_parameters`::
此变量会以原样插入到实际 `ErrorLog` 语句之前
（缩进为 2）。
+
此参数的用例可能是通过使用
`SetEnvIf` / `SetEnv` 启用条件日志，或为此 ErrorLog 设置自定义 `LogFormat`
https://httpd.apache.org/docs/2.4/logs.html[Apache 的核心文档]。
====

[[apache_vhosts__customlogs]]
`https://httpd.apache.org/docs/2.4/mod/mod_log_config.html#customlog[customlogs]`::
自定义日志的数组。
每个条目可以是字符串（不会自动加引号）或复杂数据类型：
+
====
`path`:: 
路径。
会用 `"` 引号包含。

`extra`::
附加字符串，附加在 `path` 之后。
不会加引号
（以允许自定义日志的复杂附加可选参数）。

`extra_parameters`::
此变量会以原样插入到循环的 `<VirtualHost>` 的末尾（缩进为 2）。
+
此参数的用例可能是通过使用
`SetEnvIf` / `SetEnv` 启用条件日志，或为此特定自定义日志设置自定义 `LogFormat`
根据 https://httpd.apache.org/docs/2.4/logs.html[Apache 的 mod_log_config 文档]。
====


`extra_parameters`::
此变量将以原样插入到循环的 `<VirtualHost>` 的最后（缩进为 2）。

[[apache_vhosts_ssl]]
[source,yaml]
----
apache_vhosts_ssl: []
----

对于列表中的每个条目，
将生成一个 `<VirtualHost>` 指令，监听
`{{ apache_listen_ip }}:{{ apache_listen_port_ssl }}`。

列表中的每个条目可以具有以下属性
（请查阅 <<example_playbooks>> 部分获取示例）
（请查阅官方文档链接页面以获取它们代表的实际 Apache 指令的文档）。

`https://httpd.apache.org/docs/2.4/mod/core.html#servername[servername]`（必需）::

`https://httpd.apache.org/docs/2.4/mod/core.html#serveralias[serveralias]`::

`https://httpd.apache.org/docs/2.4/mod/core.html#serveradmin[serveradmin]`::

`https://httpd.apache.org/docs/2.4/mod/core.html#documentroot[documentroot]`::

`documentroot__link:https://httpd.apache.org/docs/2.4/mod/core.html#servername[allowoverride]`::
`AllowOverride` 指令用于 `DocumentRoot` 的 `<Directory>` 内。 +
默认为 `apache_vhosts_default_documentroot__allowoverride` 的值。

`documentroot__link:https://httpd.apache.org/docs/2.4/mod/core.html#options[options]`::
`Options` 指令用于 `DocumentRoot` 的 `<Directory>` 内。 
默认为 `apache_vhosts_default_documentroot__options` 的值。

`no_actual_ssl`:: 
如果设置为 True，则 `<VirtualHost>` 将没有 SSL* 选项。
仅在您想要定义的 http 到 https 重定向时使用。

https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslcertificatefile[ssl_certificate_file]（必需）：:
https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslcertificatekeyfile[ssl_certificate_key_file]（必需）：:
https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslcertificatechainfile[ssl_certificate_chain_file]::
_请注意这是已弃用的。_

https://httpd.apache.org/docs/2.4/mod/mod_log_config.html#logformat[`logformat`]::

`https://httpd.apache.org/docs/2.4/mod/core.html#loglevel[loglevel]`::

`https://httpd.apache.org/docs/2.4/mod/core.html#errorlog[errorlog]`::
相当于 <<apache_vhosts__errorlog,apache_vhosts.errorlog>>。

`https://httpd.apache.org/docs/2.4/mod/mod_log_config.html#customlog[customlogs]`::
自定义日志的数组。
相当于 <<apache_vhosts__customlogs,apache_vhosts.customlogs>>。

`extra_parameters`::
此变量在循环的 `<VirtualHost>` 的最后插入（缩进为 2）。

[source,yaml]
----
apache_ignore_missing_ssl_certificate: true
----
如果设置为 `false`，`apache_vhosts_ssl` 的特定条目只有在存在其 `sslcertificatefile` 时才会生成。

[source,yaml]
----
apache_ssl_protocol: "All -SSLv2 -SSLv3"
apache_ssl_cipher_suite: "AES256+EECDH:AES256+EDH"
----
这些变量用作每个 `apache_vhosts_ssl` 的默认值。
它们的命名方式与所用角色变量相同
（当然，除了前缀）。
请查阅 https://httpd.apache.org/docs/current/mod/mod_ssl.html[
Apache 的文档]
以获取它们代表的实际 Apache 指令的文档。


[source,yaml]
----
apache_vhosts_default_documentroot__allowoverride: "All"
apache_vhosts_default_documentroot__options: "-Indexes +FollowSymLinks"
----


[[public_vars]]
== 📜 由此角色定义的事实/变量

此部分列出的每个变量
在执行此角色时动态定义（并且只能通过 `ansible.builtin.set_facts` 重写）_并_
用于的不仅仅是内部使用。


[[apache__service]]
.`pass:[apache__service]`
****
.示例用法在此角色之外：
[source,yaml]
----
# 角色的处理程序文件
- name: 重新启动 apache2
  ansible.builtin.service:
    name: "{{ apache__service | default('apache2') }}"
    state: restarted
----
****


[[apache__daemon]]
.`pass:[apache__daemon_dir]`, `pass:[apache__daemon]`
****
可执行名称和 `apache2` 命令的目录。
****


[[apache__server_root_dir]]
.`pass:[apache__server_root_dir]`
****
包含所有 Apache2 配置的目录（在 `/etc` 中）。
****

[[debian_is_different_note]]
[NOTE]
====
在处理以下配置值时，您需要记住：

[quote,在 Debian 10 的 /etc/apache2/apache2.conf 中发现的评论]
______
Debian 中的 Apache 2 网络服务器配置与
上游建议的配置方式相当不同。这是因为 Debian 的
默认 Apache2 安装试图使添加和删除模块、
虚拟主机和额外配置指令尽可能灵活，以便尽可能简化变更和管理服务器的自动化。
______

这意味着 `pass:[apache__server_root_dir]`
*在 Debian 中* 看起来如下：

.`tree /etc/apache2` 在新安装的 Debian 10 机器上
----
.
├── apache2.conf
├── conf-available
│   ├── charset.conf
│   ├── localized-error-pages.conf
│   ├── other-vhosts-access-log.conf
│   ├── php7.4-fpm.conf
│   ├── security.conf
│   └── serve-cgi-bin.conf
├── conf-enabled
│   ├── charset.conf -> ../conf-available/charset.conf
│   └── …
├── envvars
├── magic
├── mods-available
│   ├── access_compat.load
│   ├── alias.load
│   ├── alias.conf
│   └── …
├── mods-enabled
│   ├── access_compat.load -> ../mods-available/access_compat.load
│   ├── alias.conf -> ../mods-available/alias.conf
│   ├── alias.load -> ../mods-available/alias.load
│   └── …
├── ports.conf
├── sites-available
│   ├── 000-default.conf
│   └── default-ssl.conf
└── sites-enabled
    └── 000-default.conf -> ../sites-available/000-default.conf
----

而 # 在其他系统中看起来是这样的#：

.`tree /etc/apache2` 在新安装的 CentOS 8 机器上
----
.
├── conf
│   ├── httpd.conf
│   └── magic
├── conf.d
│   ├── autoindex.conf
│   ├── ssl.conf
│   ├── userdir.conf
│   └── welcome.conf
├── conf.modules.d
│   ├── 00-base.conf
│   ├── 00-dav.conf
│   ├── 00-lua.conf
│   ├── 00-mpm.conf
│   ├── 00-optional.conf
│   ├── 00-proxy.conf
│   ├── 00-ssl.conf
│   ├── 00-systemd.conf
│   ├── 01-cgi.conf
│   ├── 10-h2.conf
│   ├── 10-proxy_h2.conf
│   └── README
├── logs -> ../../var/log/httpd
│   └── …
└── modules -> ../../usr/lib64/httpd/modules
    ├── mod_access_compat.so
    ├── mod_actions.so
    ├── mod_alias.so
    └── …
----
====


[[apache__primary_configuration_file_path]]
.`pass:[apache__primary_configuration_file_path]`
****
Apache2 的主要配置文件，
`http://httpd.apache.org/docs/2.4/mod/core.html#include` 包含所有其他文件并包含一些其他指令。

.查看如何包含的内容
[TIP]
====
Debian 的 Apache2 包含指令如下，在 `pass:[apache__primary_configuration_file_path]` 中找到：

[source,ini]
----
# 包含模块配置：
IncludeOptional mods-enabled/*.load
IncludeOptional mods-enabled/*.conf

# 包含要监听的端口列表
Include ports.conf

# 包含的目录忽略编辑器和 dpkg 的备份文件，
# 包含通用语句片段

IncludeOptional conf-enabled/*.conf
# 包含虚拟主机配置：
IncludeOptional sites-enabled/*.conf
----

RHEL 的 Apache2 包含指令如下，在 CentOS 8 机器上的 `pass:[apache__primary_configuration_file_path]` 中：

[source,ini]
----
# 动态共享对象（DSO）支持
#
# 要使用构建为 DSO 的模块的功能，您
# 必须在此位置放置相应的 `LoadModule` 行，以便
# 其包含的指令在被使用之前是可用的。
# 静态编译的模块（通过 `httpd -l` 列出的）不需要在此处加载。
#
# 例如：
# LoadModule foo_module modules/mod_foo.so
Include conf.modules.d/*.conf

# 补充配置：
IncludeOptional conf.d/*.conf
----
====
****


[[apache__ports_configuration_file]]
.`pass:[apache__ports_configuration_file]`
*****
Apache2 配置文件，包含用于确定传入连接的监听端口的指令。

在某些系统上，这与 `pass:[apache__primary_configuration_file_path]` 相同，
但在某些情况下，它是由所述的 `pass:[apache__primary_configuration_file_path]` `http://httpd.apache.org/docs/2.4/mod/core.html#include` 的一个单独文件。
*****


[[apache__server_conf_dir]]
.`pass:[apache__server_conf_dir]`
****
包含所有 http://httpd.apache.org/docs/2.4/mod/core.html#include 的文件的目录。

此目录可能不会被 `Include` 本身，但下级目录可能会被 `Include`。
请查阅 <<apache__primary_configuration_file_path>> 中的 NOTE/TIP，
了解不同操作系统默认包含的目录。
****

[[apache__default_log_dir]]
.`pass:[apache__default_log_dir]`
****
默认用于所有虚拟主机的 `/var` 中的目录。

以下输出显示主要发行版的此文件夹的典型默认内容
的内容：

.RedHat
----
[root@instance-py3-ansible-5 /]# ls -l /var/log/httpd/
total 8
-rw-r--r-- 1 root root   0 Jun 11 11:16 access_log
-rw-r--r-- 1 root root 980 Jun 11 11:16 error_log
-rw-r--r-- 1 root root   0 Jun 11 11:16 ssl_access_log
-rw-r--r-- 1 root root 328 Jun 11 11:16 ssl_error_log
-rw-r--r-- 1 root root   0 Jun 11 11:16 ssl_request_log
----

.Debian
----
root@instance-py3-ansible-5-debian10:/# ls -l /var/log/apache2
total 4
-rw-r----- 1 root adm     0 Aug 29 10:17 access.log
-rw-r----- 1 root adm  2133 Aug 29 10:18 error.log
-rw-r--r-- 1 root root    0 Aug 29 10:18 local2-error.log
-rw-r----- 1 root adm     0 Aug 29 10:17 other_vhosts_access.log
----
****


[[tags]]
== 🏷️ 标签

// 请查看 https://github.com/tribe29/ansible-collection-tribe29.checkmk/blob/main/roles/server/README.md#tags
// 以获得使用标签分组任务的绝佳示例

任务标记如下：
https://docs.ansible.com/ansible/latest/user_guide/playbooks_tags.html#adding-tags-to-roles[标签]：

[cols="1,1"]
|===
|标签 | 目的

2+| 此角色尚未正式记录标签。

// | download-xyz
// |
// | install-prerequisites
// |
// | install
// |
// | create-xyz
// |
|===

您可以使用 Ansible 跳过任务，或仅通过使用这些标签运行某些任务。默认情况下，当未指定标签时，将运行所有任务。


[[dependencies]]
== 👫 依赖关系
// 其他角色的列表应在此处列出，
// 以及可能需要为其他角色设置的参数的详细信息，
// 或从其他角色使用的变量。



[[example_playbooks]]
== 📚 示例剧本用法
// 包括在剧本中使用此角色进行常见场景的示例对于用户始终是有益的。

[NOTE]
====
此角色是 https://github.com/JonasPammer/ansible-roles[
我许多兼容目的特定角色的一部分]。

机器需要准备好。
在 CI 中，此操作是在 `molecule/resources/prepare.yml` 中完成的
其软依赖关系来自 `requirements.yml`：

.link:molecule/resources/prepare.yml[]
[source,yaml]
----
---
- name: prepare
  hosts: all
  become: true
  gather_facts: false

  roles:
    - role: jonaspammer.bootstrap
    #    - name: jonaspammer.core_dependencies
----

以下图表是此角色的 "软依赖关系" 的汇编，
以及它们的软依赖关系的递归树。

image:https://raw.githubusercontent.com/JonasPammer/ansible-roles/master/graphs/dependencies_apache2.svg[
requirements.yml 依赖图]
====


.标准安装（无变量）
====
*以下 yaml:
+
[source,yaml]
----
roles:
  - role: jonaspammer.apache2
----
+
生成以下虚拟主机:
+
[source]
-----
# Ansible 管理
DirectoryIndex index.php index.html
<VirtualHost *:80>
    ServerName local.dev
    DocumentRoot "/var/www/html"

    <Directory "/var/www/html">
        AllowOverride All
        Options -Indexes +FollowSymLinks
        Require all granted
    </Directory>
</VirtualHost>
-----
+
作为参考，这是 Debian/Ubuntu 系统随附的默认虚拟主机
（可以通过将 `apache_remove_default_vhost` 设置为 true 来删除）
+
[source]
-----
<VirtualHost *:80>
        ServerAdmin webmaster@localhost
        DocumentRoot /var/www/html

        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
-----

未给出角色配置的情况下，与仅仅自己安装 Apache2 的偏差如下：

* 默认启用某些模块 (`<<apache_mods_enabled>>`)。
* 系统将具有上述演示的虚拟主机。
* 在初始安装时，如果之前没有名为 `favicon.ico` 的文件，则会将名为 `favicon.ico` 的文件放入 `/var/www/html`。
此默认图标类似于在维基媒体上找到的 Ansible 徽标。

_请注意，此角色不会*删除 `/var/www/html` 的内容
（即使是由/在 apache2 初始安装后创建的文件）。_
====


.记录
====
* 以下 yaml：
+
[source,yaml]
----
roles:
  - role: jonaspammer.apache2

vars:
  apache_vhost_filename: "local2.dev.conf"
  apache_vhosts:
    - servername: "wwww.local2.dev"
      loglevel: info
      errorlog: "{{ apache__default_log_dir }}/local2-error.log"
      customlog:
        path: "${{ apache__default_log_dir }}/local2-access.log"
        extra: "combined"
----
+
生成以下虚拟主机：
+
[source]
-----
# Ansible 管理。

TODO
-----
====


.使用 `extra_parameters`
====
[TIP]
======
yaml 中行末的管道符号表示后续任何缩进文本应被解释为多行标量值。
请参阅 https://yaml-multiline.info/[yaml-multiline.info] 获取交互式解释。
======

* 以下 yaml：
+
[source,yaml]
----
roles:
  - role: jonaspammer.apache2

vars:
  apache_vhost_filename: "myvhost.conf"
  apache_vhosts:
    - servername: "www.local.dev"
      serveralias: "local.dev"
      documentroot: "/var/www/html"
      extra_parameters: |
          # 将所有请求重定向到 'www' 子域。Apache 2.4+
          RewriteEngine On
          RewriteCond %{HTTP_HOST} !^www\. [NC]
          RewriteRule ^(.*)$ %{REQUEST_SCHEME}://www.%{HTTP_HOST}%{REQUEST_URI} [R=302,L]
----
+
生成以下虚拟主机：
+
[source]
-----
# Ansible 管理。

TODO
-----


* 以下 yaml：
+
[source,yaml]
----
roles:
  - role: jonaspammer.apache2

vars:
  apache_vhost_filename: "myvhost.conf"
  apache_vhosts:
    - servername: "srvcmk.intra.jonaspammer.com"
      extra_parameters: |
        Redirect / {{ checkmk_site_url }}

----
+
生成以下虚拟主机：
+
[source]
-----
# Ansible 管理。
DirectoryIndex index.php index.html
<VirtualHost *:80>
    ServerName srvcmk.intra.jonaspammer.com

    Redirect / http://srvcmk.intra.jonaspammer.at/master
</VirtualHost>
-----
====

.创建您自己的虚拟主机文件 / 集成到角色
====
_此 apache2 角色可以在玩法中多次执行，其主要目的在于
https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html#using-allow-duplicates-true[允许此功能]
来创建虚拟主机。_

[source,yaml,subs="+quotes,macros"]
----
- tasks:
    pass:[#]...
    - name: 生成 Apache2 虚拟主机。
      ansible.builtin.#include_role#: "apache2"
      vars:
        #apache_vhost_filename: "myapp.conf"#
        apache_vhosts:
          - servername: "www.myapp.dev"
            serveralias: "myapp.dev"
            DocumentRoot: "/opt/myapp"
    pass:[#]...
----
====


[[tested-distributions]]
== 🧪 测试分发版

一个角色可以在不同的 *分发版* 上工作，例如 Red Hat 企业 Linux (RHEL)，
尽管没有对此确切发行版进行测试。

// 好的参考资料 -- 大多数星级和钉住的 geerlingguy 项目的参考资料：
// https://github.com/geerlingguy/ansible-role-docker/blob/master/.github/workflows/ci.yml
|===
| 操作系统系列 | 分发版 | 分发版发布日期 | 分发版结束日期 | 附带的 Docker 镜像

// https://endoflife.date/rocky-linux
| Rocky
| Rocky Linux 8 (https://www.howtogeek.com/devops/is-rocky-linux-the-new-centos/[RHEL/CentOS 8 in disguise])
| 2021-06
| 2029-05
| https://github.com/geerlingguy/docker-rockylinux8-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-rockylinux8-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Rocky
| Rocky Linux 9
| 2022-07
| 2032-05
| https://github.com/geerlingguy/docker-rockylinux9-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-rockylinux9-ansible/workflows/Build/badge.svg?branch=master[CI]]

// https://endoflife.date/fedora (13 个月)
| RedHat
| Fedora 39
| 2023-11
| 2024-12
| https://github.com/geerlingguy/docker-fedora39-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-fedora39-ansible/workflows/Build/badge.svg?branch=master[CI]]

// https://ubuntu.com/about/release-cycle
| Debian
| Ubuntu 20.04 LTS
| 2021-04
| 2025-04
| https://github.com/geerlingguy/docker-ubuntu2004-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-ubuntu2004-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Debian
| Ubuntu 22.04 LTS
| 2022-04
| 2027-04
| https://github.com/geerlingguy/docker-ubuntu2204-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-ubuntu2204-ansible/workflows/Build/badge.svg?branch=master[CI]]

// https://wiki.debian.org/DebianReleases
// https://wiki.debian.org/LTS
| Debian
| Debian 11
| 2021-08
| 2024-06 (2026-06 LTS)
| https://github.com/geerlingguy/docker-debian11-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-debian11-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Debian
| Debian 12
| 2023-06
| 2026-06 (2028-06 LTS)
| https://github.com/geerlingguy/docker-debian12-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-debian12-ansible/workflows/Build/badge.svg?branch=master[CI]]
|===


[[tested-ansible-versions]]
== 🧪 测试的 Ansible 版本

测试的 ansible 版本尽量与
https://github.com/ansible-collections/community.general#tested-with-ansible[
Ansible `community.general` 集合的支持模式]保持一致。
在写作时是：

* 2.13（Ansible 6）
* 2.14（Ansible 7）
* 2.15（Ansible 8）
* 2.16（Ansible 9）


[[development]]
== 📝 开发
// 项目的约定徽章
https://conventionalcommits.org[image:https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg[规范化提交]]
https://results.pre-commit.ci/latest/github/JonasPammer/ansible-role-apache2/master[image:https://results.pre-commit.ci/badge/github/JonasPammer/ansible-role-apache2/master.svg[pre-commit.ci 状态]]
// image:https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white[pre-commit, link=https://github.com/pre-commit/pre-commit]

[[development-system-dependencies]]
=== 📌 开发机器依赖

* Python 3.10 或更高版本
* Docker

[[development-dependencies]]
=== 📌 开发依赖
开发依赖在名为 `requirements-dev.txt` 的
https://pip.pypa.io/en/stable/user_guide/#requirements-files[pip 依赖文件]中定义。
以下为 Linux 的示例安装说明：

----
# "可选": 创建 Python 虚拟环境并为当前 shell 会话激活它
$ python3 -m venv venv
$ source venv/bin/activate

$ python3 -m pip install -r requirements-dev.txt
----

[[development-guidelines]]
=== ℹ️ Ansible 角色开发指南

请查看我的 https://github.com/JonasPammer/cookiecutter-ansible-role/blob/master/ROLE_DEVELOPMENT_GUIDELINES.adoc[
Ansible 角色开发指南]。

如果您感兴趣，我还写下了一些
https://github.com/JonasPammer/cookiecutter-ansible-role/blob/master/ROLE_DEVELOPMENT_TIPS.adoc[
一般 Ansible 角色开发的最佳实践]。

[[versioning]]
=== 🔢 版本控制

版本通过 https://git-scm.com/book/en/v2/Git-Basics-Tagging[标签] 定义，
这些标签反过来被 https://galaxy.ansible.com/docs/contributing/version.html[Ansible Galaxy 识别和使用]。

*版本不得以 `v` 开头。*

当新的标签被推送时，https://github.com/JonasPammer/ansible-role-apache2/actions/workflows/release-to-galaxy.yml[
一个 GitHub CI 工作流] 
(image:https://github.com/JonasPammer/ansible-role-apache2/actions/workflows/release-to-galaxy.yml/badge.svg[发布 CI])负责将角色导入我的 Ansible Galaxy 账户。

[[testing]]
=== 🧪 测试
每次提交时都会使用 GitHub 工作流运行自动测试。

测试主要围绕在不同的 <<tested-distributions,varying set of linux distributions>> 上运行 https://molecule.readthedocs.io/en/latest/[Molecule]
以及使用 <<tested-ansible-versions,various ansible versions>>。

Molecule 测试还包含一个步骤，对所有 Ansible 剧本进行 lint 检查，使用
https://github.com/ansible/ansible-lint#readme[`ansible-lint`] 检查最佳实践和可能改进的行为。

要运行测试，只需在命令行运行 `tox`。
您可以传递一个可选的环境变量来定义将被 Molecule 生成的 Docker 容器的分发版：

----
$ MOLECULE_DISTRO=ubuntu2204 tox
----

查看 link:.github/workflows/ci.yml[] 中定义的 `MOLECULE_DISTRO` 的可能值列表。

==== 🐛 调试 Molecule 容器

1. 使用选项 `MOLECULE_DESTROY=never` 运行您的 Molecule 测试，例如：
+
[subs="quotes,macros"]
----
$ *MOLECULE_DESTROY=never MOLECULE_DISTRO=#ubuntu1604# tox -e py3-ansible-#5#*
...
  TASK [ansible-role-pip : (已删除).] pass:[************************]
  failed: [instance-py3-ansible-9] => changed=false
...
 pass:[___________________________________ 摘要 ____________________________________]
  pre-commit: commands succeeded
ERROR:   py3-ansible-9: commands failed
----

2. 查找 Molecule 提供的 Docker 容器的名称：
+
[subs="quotes"]
----
$ *docker ps*
#30e9b8d59cdf#   geerlingguy/docker-debian12-ansible:latest   "/lib/systemd/systemd"   8 minutes ago   Up 8 minutes                                                                                                    instance-py3-ansible-9
----

3. 进入容器的 bash shell，进行调试：
+
[subs="quotes"]
----
$ *docker exec -it #30e9b8d59cdf# /bin/bash*

root@instance-py3-ansible-2:/#
----
+
[TIP]
====
如果您尝试调试的错误是您在 `verify.yml` 步骤中的一部分，而不是实际的 `converge.yml`，
您可能想知道 Ansible 的模块输出（`vars`）、主机（`hostvars`）和环境变量已存储在提供程序和 Docker 机器中，
路径如下：
* `/var/tmp/vars.yml`（包含 `hostvars` 键下的主机变量）
* `/var/tmp/environment.yml`
`grep`、`cat` 或根据您的需要进行转移！
====
+
[TIP]
=====
您也许想知道上述注释中提到的文件是在给定工作流运行的 *GitHub CI 产物* 中附加的。 +
这使得能够检查运行之间的差异，从而帮助调试导致比特腐烂或故障的原因。

image::https://user-images.githubusercontent.com/32995541/178442403-e15264ca-433a-4bc7-95db-cfadb573db3c.png[]
=====

4. 调试完成后，退出并销毁容器：
+
[subs="quotes"]
----
root@instance-py3-ansible-2:/# *exit*

$ *docker stop #30e9b8d59cdf#*

$ *docker container rm #30e9b8d59cdf#*
_or_
$ *docker container prune*
----

==== 🐛 本地调试安装包版本

尽管这是 tox 3 的一个标准特性，但 https://github.com/tox-dev/tox/pull/2794[现在] 只在 Tox 识别到 CI 变量时发生。
例如：

----
$ CI=true tox
----


[[development-container-extra]]
=== 🧃 提示: 理想的容器化开发环境

该项目提供了“1-点击容器化开发环境”的定义。

此容器甚至允许在里面运行 Docker 容器（Docker-In-Docker, dind），
允许执行 Molecule。

使用方法：

1. 确保您满足 link:https://code.visualstudio.com/docs/remote/containers#_system-requirements[
   Visual Studio Code 开发容器的系统要求]，
   可选地遵循链接页面部分中的 __安装__ 部分。 +
   这包括：安装 Docker、安装 Visual Studio Code 和安装必要的扩展。
2. 将项目克隆到您的机器上
3. 在 Visual Studio Code 中打开 repo 的文件夹（_文件 - 打开文件夹..._）。
4. 如果您在右下角收到提示，告知您存在开发容器定义，
您可以按随附按钮以进入。
*否则，* 您还可以通过执行 Visual Studio 命令 `Remote-Containers: Open Folder in Container` 来自己执行这一操作（_查看 - 命令面板_ -> _输入提到的命令_）。

[TIP]
====
我建议您有时使用 `Remote-Containers: Rebuild Without Cache and Reopen in Container`，因为开发容器功能有时识别不了所做的更改。
====

[NOTE]
=====
您可能需要配置主机系统，以便容器能够使用您的 SSH/GPG 密钥。

该过程在官方开发容器文档的“与容器共享 Git 凭证”部分中描述：https://code.visualstudio.com/remote/advancedcontainers/sharing-git-credentials[
在官方开发容器文档中]。
=====


[[cookiecutter]]
=== 🍪 CookieCutter

该项目应与
https://github.com/JonasPammer/cookiecutter-ansible-role[最初模板的 CookieCutter]保持同步
使用 https://github.com/cruft/cruft[cruft]（如果可能）或手动更改（如果需要）尽可能保持一致。

.官方示例用法 `cruft update`
____
image::https://raw.githubusercontent.com/cruft/cruft/master/art/example_update.gif[官方示例用法 `cruft update`]
____

==== 🕗 变更日志
当新的标签被推送时，适当的 GitHub 版本将由库维护者创建，
以提供具有标题和描述的合理变更日志。


[[pre-commit]]
=== ℹ️ 一般代码检查和样式约定
一般代码检查和样式约定由各种 https://pre-commit.com[`pre-commit`] 钩子至少在某种程度上自动遵循标准。

每次提交时，都会使用 https://pre-commit.ci[`pre-commit.ci`] 运行 pre-commit 的自动执行<<note_pre-commit-ci,*>>。
拉取请求甚至会自动通过同一工具进行修复，
至少通过自动更改文件的钩子。

[NOTE]
====
请勿混淆：
尽管某些 pre-commit 钩子可能会警告您有故障的代码或语法分析，但这并不是 pre-commit 实际上运行的测试套件。
有关测试的信息，请查阅 <<testing>>。
====

[TIP]
====
[[note_pre-commit-ci]]
然而，我建议您自己将 pre-commit 集成到本地开发工作流中。

这可以通过在克隆项目的目录中运行 `pre-commit install` 来实现。
这样会使 Git 在您进行每次提交时运行 pre-commit 检查，
如果某个钩子发出警报则中止该提交。

您还可以通过运行 `pre-commit run --all-files` 随时执行 pre-commit 的钩子。
====


[[contributing]]
== 💪 贡献
image:https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square[欢迎 PR]
https://open.vscode.dev/JonasPammer/ansible-role-apache2[image:https://img.shields.io/static/v1?logo=visualstudiocode&label=&message=Open%20in%20Visual%20Studio%20Code&labelColor=2c2c32&color=007acc&logoColor=007acc[在 Visual Studio Code 中打开]]

// 包含在 README.adoc
:toc:
:toclevels: 3

以下部分是通用的，旨在帮助新贡献者。
本项目的实际“开发文档”在 <<development>>下找到。

=== 🤝 前言
首先，感谢您考虑为本项目做出贡献。

遵循这些指导方针有助于传达您对管理和开发此开源项目的开发人员的时间的尊重。
作为回报，他们应在解决您的问题、评估更改和帮助您最终确定您的拉取请求中相应地回报这种尊重。

[[cookiecutter--contributing]]
=== 🍪 CookieCutter
本项目的许多文件归
https://github.com/JonasPammer/cookiecutter-ansible-role[最初模板的 CookieCutter]所有。

请检查您所考虑的编辑是否确实适用于模板，
如果是，请在那儿进行适当的更改。
您的更改也可能部分适用于模板，
以及部分适用于本项目的特定内容，
在这种情况下，您将创建多个 PR。

=== 💬 规范化提交

普通贡献者不必担心遵循
https://github.com/JonasPammer/JonasPammer/blob/master/demystifying/conventional_commits.adoc[__该规范__]
https://www.conventionalcommits.org/en/v1.0.0/[__定义__]，
因为拉取请求被压缩合并到一个提交中。
只有核心贡献者，即有权推送到本项目分支的人，必须遵循它
（例如，以便使自动版本确定和变更日志生成工作）。

=== 🚀 开始

对本库的贡献可以通过问题和拉取请求（PR）来进行。
以下是一些涵盖两者的通用指导方针：

* 在创建自己的问题之前，请搜索现有的问题和 PR。
* 如果您以前从未贡献过，请参阅 https://auth0.com/blog/a-first-timers-guide-to-an-open-source-project/[
  Auth0 博客上的初学者指南]，获取启动建议和资源。

==== 问题

问题应用于报告问题，请求新功能或在创建 PR 之前讨论潜在更改。
当您 https://github.com/JonasPammer/ansible-role-apache2/issues/new[
创建新问题时]，将加载一个模板，该模板将指导您收集并提供我们需要调查的信息。

如果您发现一个问题涉及您所遇到的问题，
请将您自己的重现信息添加到现有问题中*而不是创建新问题*。
添加一个 https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/[反应] 
也可以帮助我们的维护者表明某个问题影响的不仅仅是报告人。

==== 拉取请求

对本项目的 PR 始终受到欢迎，并且可以快速将您的修复或改进纳入下一个版本。
https://blog.ploeh.dk/2015/01/15/10-tips-for-better-pull-requests/[一般而言]，PR 应：

* 只修复/添加相关功能*或*解决广泛的空白/样式问题，而不是两者。
* 为修复或更改的功能添加单元或集成测试（如果测试套件已经存在）。
* *处理单一关注点*
* *在代码库中添加文档*
* 附带完整的拉取请求模板（在创建 PR 时自动加载）。

对于涉及核心功能或需要重大更改的更改（例如，主要版本的发布），
最好先提交一个问题以讨论您的提案。

总的来说，我们遵循“叉子和拉取”的 Git 工作流

1. 将库叉到您自己的 Github 账户
2. 将项目克隆到您的机器上
3. 在本地创建一个带有简洁但描述性名称的分支
4. 将更改提交到该分支
5. 遵循与本库特定的任何格式和测试指南
6. 将更改推送到您的分叉
7. 在我们的库中打开一个 PR，并遵循 PR 模板，以便我们有效地审核更改。


[[changelog]]
== 🗒 变更日志
有关本库的相应内容，
请参阅 https://github.com/JonasPammer/ansible-role-apache2/releases[发布页面]
以获取人类可读的变更日志。

请注意，本项目遵守语义版本控制。
请报告任何由于小版本更新而意外造成的破坏性更改。


[[license]]
== ⚖️ 许可证

.link:LICENSE[]
----
MIT 许可证

版权所有 (c) 2022, Jonas Pammer

特此免费授予任何获得该软件及其相关文档文件（“软件”）副本的人，限制性地处理
软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售
软件的副本，并允许向其提供软件的人这样做，遵循以下条件：

上述版权声明和本许可证声明应包含在所有
软件的副本或实质性部分中。

软件是"按原样"提供的，不提供任何类型的保证，无论是明示或暗示，包括但不限于对适销性、
特定用途适用性和非侵权的保证。在任何情况下，作者或版权持有者均不对任何索赔、损害或其他
责任承担任何责任，无论是在合同、侵权或其他方面，因使用或与使用有关的
软件或其他交易而产生。
----