# Nginx

针对 [Nginx](http://nginx.org) 应用的 Docker 镜像，用于提供 Nginx 服务。容器详细使用说明可参考仓库：[Gitee](https://www.gitee.com/endial/studylife.git) 或 [Github](https://www.github.com/endial/studylife.git)中`服务器运维`相应文档。

使用说明可参照：[官方说明](http://nginx.org/en/docs/)

![logo-nginx](img/logo-nginx.png)

**版本信息：**

- 1.29、latest
- 1.28

**镜像信息：**

* 镜像地址：
  - 阿里云: registry.cn-shenzhen.aliyuncs.com/colovu/nginx:latest
  - Colovu Registry: docker.colovu.com/colovu/nginx:latest
  - 依赖镜像：colovu/debian:12

> 后续相关命令行默认使用 Aliyun ACR 镜像服务器做说明

## TL;DR

Docker 快速启动命令：

```shell
# 从 Registry 服务器下载镜像并启动
$ docker run -d -p 80:8080 registry.cn-shenzhen.aliyuncs.com/colovu/nginx:latest
```

- `registry.cn-shenzhen.aliyuncs.com/colovu/imgname:<TAG>`：镜像名称及版本标签 TAG；标签不指定时默认使用最新版本

启动后，可以使用浏览器访问:`http://localhost/`，出现默认的 Nginx 首页。

Docker-Compose 快速启动命令：

```shell
# 从 Gitee 下载 Compose 文件
$ curl -sSL -o https://gitee.com/colovu/docker-nginx/raw/master/docker-compose.yml

# 从 Github 下载 Compose 文件
$ curl -sSL -o https://raw.githubusercontent.com/colovu/docker-nginx/master/docker-compose.yml

# 创建并启动容器
$ docker-compose up -d
```

---

## 默认对外声明

### 端口

- 8080：HTTP 端口
- 8443：HTTPS 端口

### 数据卷

镜像默认提供以下数据卷定义，默认数据分别存储在自动生成的应用名对应`nginx`子目录中：

```shell
/srv/nginx/conf           # 配置文件
/srv/nginx/data           # 数据文件，主要存放应用数据
/srv/nginx/cert           # 证书文件存放目录
/srv/nginx/log            # 日志文件
/var/run/nginx            # 进程运行PID文件
```

如果需要持久化存储相应数据，需要**在宿主机建立本地目录**，并在使用镜像初始化容器时进行映射。宿主机相关的目录中如果不存在对应应用`nginx`的子目录或相应数据文件，则容器会在初始化时创建相应目录及文件。

## 容器配置

在初始化 `Nginx` 容器时，如果没有预置配置文件，可以在命令行中设置相应环境变量对默认参数进行修改。类似命令如下（配置环境变量`APP_ENV_KEY_NAME`的值为`key_value`）：

```shell
$ docker run -d -e "APP_ENV_KEY_NAME=key_value" registry.cn-shenzhen.aliyuncs.com/colovu/nginx:latest
```

### 自动变量替换

针对应用配置文件中的配置项，支持由环境变量名自动替换生成，该类环境变量需要使用统一前缀，定义规则为：`APP_CFG_*=<val>`

- `APP_CFG_`：环境变量自动替换标识，具备该前缀的环境变量会被自动处理并更新至配置文件
- `*`：配置文件中对应的配置项名，大小写需要符合实际参数名要求；特殊字符需要符合`特殊字符替换规则`
- `<val>`：配置项对应值

**特殊字符替换规则**：

因为 Shell 变量只能以字母、数字和下划线组成，针对'xml'、'ini'等配置文件中使用的'.'、'-'等特殊字符，需要进行重定义及转换。预定义如下：

  + `_` ==> `_` : 应用配置属性中的`_`（下划线），与环境变量相同
  + `__` ==> `.` : 应用配置属性中的`.`（半角点），在环境变量中由`__`（双下划线）表示
  + `___` ==> `-` : 应用配置属性中的`-`（中划线），在环境变量中由`___`（三下划线）表示

例如：

```shell
# 常用于`key-value`类型的配置
APP_CFG_min_wal_size=100MB
APP_CFG_max_wal_size="400MB"

# 容器启动后，应用配置文件中对应配置项生效，且设置为相应值：
min_wal_size = '100MB'
max_wal_size = '400MB'


# 常用于`xml`类型的配置
APP_CFG_fs__defaultFS=hdfs://namenode:8020
APP_CFG_yarn__log___aggregation___enable=true

# 容器启动后，应用配置文件中对应配置项生效，且设置为相应值：
  <property><name>fs.defaultFS</name><value>hdfs://namenode:8020</value></property>
  <property><name>yarn.log-aggregation-enable</name><value>true</value></property>
```

### 常规配置参数

常规配置参数用来配置容器基本属性，一般情况下需要设置，主要包括：

- 

### 常规可选参数

如果没有必要，可选配置参数可以不用定义，直接使用对应的默认值，主要包括：

- `ENV_DEBUG`：默认值：**false**。设置是否输出容器调试信息。可选值：false、no、true、yes
- `ALLOW_ANONYMOUS`：默认值：**no**。设置是否允许匿名链接。可选值：false、no、true、yes

### 集群配置参数

配置服务为集群工作模式时，通过以下参数进行配置：

- 

### TLS配置参数

配置服务使用 TLS 加密时，通过以下参数进行配置：

- 

## 安全

### 容器安全

本容器默认使用`non-root`运行应用，以加强容器的安全性。在使用`non-root`用户运行容器时，相关的资源访问会受限；应用仅能操作镜像创建时指定的路径及数据。使用`non-root`方式的容器，更适合在生产环境中使用。

如果需要赋予容器内应用访问外部设备的权限，可以使用以下两种方式：

- 启动参数增加`--privileged=true`选项
- 针对特定权限需要使用`--cap-add`单独增加特定赋权，如：ALL、NET_ADMIN、NET_RAW

如果需要切换为`root`方式运行应用，可以在启动命令中增加`-u root`以指定运行的用户。

## 注意事项

- 容器中应用的启动参数不能配置为后台运行，如果应用使用后台方式运行，则容器的启动命令会在运行后自动退出，从而导致容器退出

## 更新记录

- 2026/1/21: 更新版本为 v1.29.3
- 2023/8/3: 更新为 Nginx 1.24.0

----

本文原始来源 [Endial Fang](https://github.com/colovu) @ [Github.com](https://github.com)