从 nginx 迁移#

本指南在同一台主机上，用软件包安装的 Angie 替换软件包安装的 nginx，同时保留配置、虚拟主机、动态模块和证书。指南假定 nginx 是通过发行版软件包安装的，配置位于 /etc/nginx/，而 Angie 来自官方软件包。大多数 nginx 指令在 Angie 中可以原样使用；例外情况列在 nginx 不支持的指令中，并在下文处理。容器和使用自定义路径的构建需要额外调整，本指南不做介绍。

安装 Angie#

为您的发行版从官方软件包安装 Angie，但跳过启动和启用这两步：此时 80 和 443 端口仍被 nginx 占用。在 Debian 和 Ubuntu 上，软件包会自行尝试启动服务，而 nginx 正在运行，启动会因端口无法绑定而失败；这个失败是预期之中的，不影响安装本身。

确认二进制文件：

$ sudo angie -v
Angie version: Angie/1.12.4

软件包将配置放在 /etc/angie/ 中——angie.conf 与 http.d/、stream.d/ 目录以及指向模块目录的 modules/ 链接放在一起——日志则位于 /var/log/angie/。

复制并调整配置#

下面的步骤使用 rsync；如果没有这个命令，请安装对应的软件包。

将整个 nginx 配置复制到 /etc/angie/：
```
$ sudo rsync -a --no-links /etc/nginx/ /etc/angie/
```
--no-links 选项会跳过符号链接，并报告每一个它跳过的链接；下文会重新创建 sites-enabled/ 和 modules-enabled/ 中的符号链接，而目标位于 /etc/nginx/ 之外的链接，需要单独复制其目标。

按照 Angie 的要求重命名主配置文件：

$ sudo mv /etc/angie/nginx.conf /etc/angie/angie.conf

更新整个 Angie 配置中的路径，从主文件开始。至少需要更新：

任何仍然指向 /etc/nginx/ 的 include 路径：

# include /etc/nginx/conf.d/*.conf;
# include /etc/nginx/default.d/*.conf;
# include /etc/nginx/http.d/*.conf;
# include /etc/nginx/stream.d/*.conf;
include /etc/angie/conf.d/*.conf;
include /etc/angie/default.d/*.conf;
include /etc/angie/http.d/*.conf;
include /etc/angie/stream.d/*.conf;

# include /etc/nginx/sites-enabled/*;
include /etc/angie/sites-enabled/*;

# include /etc/nginx/modules-enabled/*.conf;
include /etc/angie/modules-enabled/*.conf;

# include /etc/nginx/mime.types;
include /etc/angie/mime.types;

pid 路径，软件包的 service 单元期望它位于 /run/angie.pid：

# pid /var/run/nginx.pid;
# -- 或 --
# pid /run/nginx.pid;
pid /run/angie.pid;

最后，访问日志和错误日志：

# access_log /var/log/nginx/access.log;
access_log /var/log/angie/access.log;

# error_log /var/log/nginx/error.log;
error_log /var/log/angie/error.log;

虚拟主机#

如果虚拟主机是通过 sites-enabled/ 包含进来的，那么 include 已经指向 /etc/angie/，文件本身也已经复制过来了，但符号链接没有——它们被 --no-links 跳过了。请重新创建这些符号链接。

列出原始文件，并记下它们指向的位置：

$ ls -l /etc/nginx/sites-enabled/

  default -> /etc/nginx/sites-available/default

这里指向的是 /etc/nginx/sites-available/，位于 /etc/nginx/ 内部，因此 Angie 那边的副本已经就位。如果目标位于该目录之外，请把它也复制到 /etc/angie/ 中。

然后针对 Angie 的副本重新创建每个符号链接：

$ sudo ln -s /etc/angie/sites-available/default \
             /etc/angie/sites-enabled/default

动态模块#

找出 nginx 配置加载的动态模块：

$ sudo nginx -T | grep load_module

  load_module modules/ngx_http_geoip2_module.so;
  load_module modules/ngx_stream_geoip2_module.so;
  ...

对于常见的第三方模块，我们发布了软件包：Angie 对应 angie-module-name，Angie PRO 对应 angie-pro-module-name。上面输出中的两个 .so 文件都来自 angie-module-geoip2 软件包。请查看软件包列表，为命令列出的每个模块安装对应的软件包；列表中没有的模块，必须为已安装的 Angie 或 Angie PRO 构建。

像 modules/ngx_http_geoip2_module.so 这样的相对 load_module 路径，是相对于前缀 /etc/angie 解析的，其中 modules 链接到软件包的模块目录，因此不需要修改。而 nginx 中的绝对路径则需要改写：在 Debian 和 Ubuntu 上改写为 /usr/lib/angie/modules/，在 RHEL 系发行版上改写为 /usr/lib64/angie/modules/。无论您使用哪种布局，都请在下面复制的模块配置文件中改写这些绝对路径。

有两种常见的方式来包含动态模块配置：

如果通过 /usr/share/nginx/modules/ 包含动态模块，更新路径：

# Load dynamic modules. See /usr/share/doc/nginx/README.dynamic.
# include /usr/share/nginx/modules/*.conf;

include /usr/share/angie/modules/*.conf;

然后复制模块配置文件：

$ sudo rsync -a /usr/share/nginx/modules/ /usr/share/angie/modules/

如果动态模块是通过 /etc/nginx/modules-enabled/ 包含进来的，那么 include 已经指向 /etc/angie/。请重新创建被 --no-links 跳过的符号链接。

列出原始文件，并记下它们指向的位置：

$ ls -l /etc/nginx/modules-enabled/

  mod-http-geoip2.conf -> /usr/share/nginx/modules-available/mod-http-geoip2.conf

这里指向的是 /usr/share/nginx/modules-available/，位于 /etc/nginx/ 之外，因此也需要复制这个目录：

$ sudo rsync -a /usr/share/nginx/modules-available/ /usr/share/angie/modules-available/

最后，重新创建每个符号链接：

$ sudo ln -s /usr/share/angie/modules-available/mod-http-geoip2.conf \
             /etc/angie/modules-enabled/mod-http-geoip2.conf

存在差异的指令#

Angie 弃用了少数几个 nginx 指令，并省略了另外几个。如果您的配置依赖其中任何一个，请参阅 nginx 不支持的指令。省略的指令会让 angie -t 报未知指令错误而失败；弃用的指令仍会被接受，但会记录一条警告，说明应改用哪个指令。

现有配置中最可能出现的是 nginx 的 keepalive_min_timeout：Angie 省略了这个指令，请将它删除。

根目录（可选）#

只有当 root 指向 /usr/share/nginx/html/ 时，才需要这一步。将其中的内容复制到 Angie 的目录中：

$ sudo rsync -a /usr/share/nginx/html/ /usr/share/angie/html/

然后更新该指令：

# root /usr/share/nginx/html;
root /usr/share/angie/html;

用户和组（可选）#

user 指令指定工作进程以哪个账户运行。Angie 的软件包会创建一个 angie 账户。原来 nginx 使用的账户仍然可用，因此这一步是可选的；如果要把工作进程切换到 Angie 账户：

# user www-data www-data;
user angie angie;

主进程以 root 身份解析配置、读取证书和密钥，因此 /etc/angie/ 的属主不需要更改。工作进程需要的，是对它们所提供内容的访问权限：

$ sudo chown -R angie:angie /usr/share/angie/html/

如果 Angie 配置中有 root 指令，更改其中指定目录的所有者，例如：

$ sudo chown -R angie:angie /var/www/html/

最终检查#

查找仍然指向 nginx 的内容：

$ grep -rn nginx /etc/angie/

逐条检查匹配结果。注释以及自带的参数文件(fastcgi_params、scgi_params、uwsgi_params)中出现 nginx 字样是无害的；真正需要关注的是仍然解析到 /etc/nginx/ 或 /var/log/nginx/ 下的路径。

测试和切换#

检查 Angie 是否接受该配置：

$ sudo angie -t

该命令会加载动态模块并解析每一个被包含的文件；修复每一条报告的错误，然后重新运行，直到测试通过。

停止 nginx，启动 Angie#

为了最小化停机时间，在停止 nginx 后立即启动 Angie：

$ sudo systemctl stop nginx && sudo systemctl start angie

启用该服务，使其在重启后自动启动：

$ sudo systemctl enable angie

确认响应现在来自 Angie：

$ curl -I localhost
HTTP/1.1 200 OK
Server: Angie/1.12.4
...

禁用 nginx#

确认 Angie 运行正常后，禁用 nginx，以免它在重启后重新占用 80 和 443 端口：

$ sudo systemctl disable nginx

证书#

如果 Certbot 此前管理着 nginx 的证书，只要把它指向新的目录布局，它就能继续为 Angie 工作。

Certbot#

certbot 的 nginx 插件会在 server root 中查找 nginx.conf，并通过 nginx 的二进制文件重载服务器。请在下一次续订之前，把它指向 Angie。

创建插件所期望的文件名：

$ sudo ln -s /etc/angie/angie.conf /etc/angie/nginx.conf

针对现有域名重新运行该插件，指定 Angie 的 server root 和二进制文件；certbot 会把这些参数与证书一起保存，并在续订时复用它们：

$ sudo certbot --nginx --nginx-server-root=/etc/angie --nginx-ctl=angie -d example.com -d www.example.com

验证续订是否能够成功：

$ sudo certbot renew --dry-run

后续续订将继续通过 Certbot 自己的定时任务进行。

内置 ACME 客户端#

Angie 无需外部客户端即可自行获取并续订证书：自动 HTTPS 展示了具体配置，从 certbot 迁移则说明了如何替换现有的 Certbot 方案。

后续步骤#

Angie 的新增功能和 Angie PRO	nginx 所没有的功能，分为开源版和商业版。
第一步	通过一个小例子了解自动 HTTPS 和统计信息 API。
模块	按模块分组的全部指令和变量参考。
说明	针对具体任务的分步指南：SSL、OIDC、集群、监控面板和自定义指标。