# Nginx 入口

> 配置基础设施门户和 nginx 设置
---

Pigsty 在基础设施节点上安装 Nginx 作为 Web 服务代理，默认使用端口 80/443。
全局参数 [`infra_portal`](/zh/docs/infra/param#infra_portal) 配置 Nginx 代理规则和上游服务。



--------


Nginx 服务器配置通过 `infra_portal` 参数指定。用户声明要通过 Nginx 代理的所有域名，以及相应的上游服务器端点或本地目录路径。

### 基本示例 {#basic-example}

```yaml
infra_portal:  # 域名和上游服务器
  home         : { domain: h.pigsty }
  grafana      : { domain: g.pigsty, endpoint: "${admin_ip}:3000", websocket: true }
  prometheus   : { domain: p.pigsty, endpoint: "${admin_ip}:9058" }
  alertmanager : { domain: a.pigsty, endpoint: "${admin_ip}:9059" }
  blackbox     : { endpoint: "${admin_ip}:9115" }
  loki         : { endpoint: "${admin_ip}:3100" }
```

### 复杂示例 {#complex-example}

```yaml
infra_portal:
  home         : { domain: home.pigsty.cc }
  grafana      : { domain: g.pgsty.com, endpoint: "${admin_ip}:3000", websocket: true }
  cc           : { domain: pigsty.cc, path: "/www/pigsty.cc" }
  en           : { domain: pigsty.io, path: "/www/pigsty.io" }
  prometheus   : { domain: p.pigsty.cc, endpoint: "${admin_ip}:9058" }
  alertmanager : { domain: a.pigsty.cc, endpoint: "${admin_ip}:9059" }
  minio        : { domain: s3.pigsty.cc, endpoint: "${admin_ip}:9001", websocket: true }
  jupyter      : { domain: lab.pigsty.cc, endpoint: "${admin_ip}:8888", websocket: true }
  repo         : { domain: repo.pigsty.cc, path: "/www/repo", index: true }
  wiki         : { domain: wiki.pigsty.cc, endpoint: "${admin_ip}:9002" }
  noco         : { domain: noco.pigsty.cc, endpoint: "${admin_ip}:8080" }
  supa         : { domain: supa.pigsty.cc, endpoint: "${admin_ip}:3001" }
  dify         : { domain: dify.pigsty.cc, endpoint: "${admin_ip}:8001" }
  pg1          : { domain: pg1.pigsty.cc, endpoint: "10.10.10.11:5432", scheme: tcp }
  pg2          : { domain: pg2.pigsty.cc, endpoint: "10.10.10.12:5432", scheme: tcp }
  pg3          : { domain: pg3.pigsty.cc, endpoint: "10.10.10.13:5432", scheme: tcp }
```



--------

## Playbook 配置 {#playbook-configuration}

可以使用 Ansible playbook 重新配置 Nginx：

```bash
./infra.yml -t nginx           # 完全重新配置 Nginx
./infra.yml -t nginx_config    # 重新生成 Nginx 配置文件
./infra.yml -t nginx_launch    # 重启 Nginx 服务
./infra.yml -t nginx_cert      # 重新生成 SSL 证书
```



-------

## 服务器 {#server}

`infra_portal` 中的每个服务器记录支持以下配置选项：

### 核心参数 {#core-parameters}

- **`domain`** - 可选的代理域名
- **`endpoint`** - 上游服务地址（IP:PORT 或套接字路径）
- **`path`** - 静态内容的本地 Web 服务器根目录
- **`scheme`** - 协议规范（http/https/tcp/udp）

### SSL/TLS 参数 {#ssl-tls-parameters}

- **`certbot`** - 启用 Let's Encrypt 证书管理
- **`cert`** - 自定义 SSL 证书文件路径
- **`key`** - 自定义 SSL 私钥文件路径

### 高级参数 {#advanced-parameters}

- **`conf`** - 自定义 Nginx 配置模板
- **`domains`** - 服务的附加域名
- **`index`** - 为静态内容启用目录列表
- **`log`** - 自定义日志文件配置
- **`websocket`** - 为实时应用启用 WebSocket 支持

### 参数使用示例 {#parameter-usage-examples}

```yaml
# 带目录列表的静态文件服务
repo: { domain: repo.pigsty.cc, path: "/www/repo", index: true }

# 启用 WebSocket 的服务
grafana: { domain: g.pigsty.cc, endpoint: "${admin_ip}:3000", websocket: true }

# 自定义 SSL 证书
secure_app: {
  domain: secure.pigsty.cc,
  endpoint: "${admin_ip}:8443",
  cert: "/etc/ssl/certs/custom.crt",
  key: "/etc/ssl/private/custom.key"
}

# Let's Encrypt 管理的证书
public_api: { domain: api.pigsty.cc, endpoint: "${admin_ip}:8080", certbot: true }

# TCP 流代理
pg_primary: { domain: pg.pigsty.cc, endpoint: "10.10.10.11:5432", scheme: tcp }
```



-------

## 使用域名 {#using-domain-names}

### DNS 解析方法 {#dns-resolution-methods}

1. **公共互联网域名** 通过 DNS 提供商
2. **内部网络 DNS** 服务器
3. **本地 `/etc/hosts`** 文件修改

### 推荐的本地配置 {#recommended-local-configuration}

对于本地开发和测试，请在您的 `/etc/hosts` 文件中添加条目：

```bash
# 添加到 /etc/hosts
<your_public_ip_address> h.pigsty g.pigsty p.pigsty a.pigsty
```

将 `<your_public_ip_address>` 替换为您的实际管理节点 IP 地址。

## HTTPS 配置 {#https-configuration}

通过 `nginx_sslmode` 参数配置 HTTPS 访问，支持以下选项：

- **`disabled`** - 仅 HTTP，无 SSL
- **`self-signed`** - 使用自签名证书（默认）
- **`provided`** - 使用提供的证书
- **`letsencrypt`** - 使用 Let's Encrypt 证书

### 证书管理 {#certificate-management}

```bash
./infra.yml -t nginx_cert      # 重新生成 SSL 证书
```

### HTTPS 访问方法 {#https-access-methods}

对于自签名证书，您可以：
- **在浏览器中信任自签名 CA**
- **使用浏览器安全绕过选项**（在 Chrome 中输入 `thisisunsafe`）
- **为生产环境配置适当的 CA 签名证书**




--------

## 服务访问示例 {#service-access-examples}

使用默认配置，服务可通过以下方式访问：

- **主页**：`http://h.pigsty` 或 `https://h.pigsty`
- **Grafana 仪表板**：`http://g.pigsty` 或 `https://g.pigsty`
- **Prometheus 指标**：`http://p.pigsty` 或 `https://p.pigsty`
- **Alertmanager**：`http://a.pigsty` 或 `https://a.pigsty`



--------

## 最佳实践 {#best-practices}

1. **使用域名** 访问服务，而不是直接使用 IP:PORT
2. **配置 DNS 解析** 或适当更新本地 hosts 文件
3. **为需要的服务启用 WebSocket 支持**（如 Grafana、Jupyter）
4. **在生产环境中使用 HTTPS** 并配置适当的证书
5. **合理组织服务** 使用有意义的子域名命名
6. **监控 Let's Encrypt 证书过期时间**
7. **通过 Nginx 集中管理 Web 服务代理** 以获得更好的管理体验
8. **使用静态文件服务** 用于文档和仓库浏览