本章节介绍 Pigsty 部署的日常管理和运维操作。
管理预案
1 - Ansible
所有 INFRA 节点上都默认安装了 Ansible,可以用于管理整套部署。
Pigsty 基于 Ansible 实现自动化管理,它遵循 基础设施即代码(Infrastructure-as-Code) 的理念。
对于管理数据库与基础设施而言,Ansible 的知识很有用,但并非必需。您只需知道如何执行 剧本(Playbook) —— 那些定义了一系列自动化任务的 YAML 文件即可。
安装
Pigsty 在 引导过程 中会尽力自动安装 ansible 及其依赖项。
如需手动安装,请使用以下命令:
# Debian / Ubuntu
sudo apt install -y ansible python3-jmespath
# EL 10
sudo dnf install -y ansible python-jmespath
# EL 8/9
sudo dnf install -y ansible python3.12-jmespath
# EL 7
sudo yum install -y ansible python-jmespath
macOS
macOS 用户可使用 Homebrew 安装:
brew install ansible
pip3 install jmespath
基础用法
运行剧本只需执行 ./path/to/playbook.yml 即可。以下是最常用的 Ansible 命令行参数:
| 用途 | 参数 | 说明 |
|---|---|---|
| 在哪里 | -l / --limit <pattern> | 限定目标主机/分组/匹配模式 |
| 做什么 | -t / --tags <tags> | 仅运行带有指定标签的任务 |
| 怎么做 | -e / --extra-vars <vars> | 传递额外的命令行变量 |
| 用什么配置 | -i / --inventory <path> | 指定配置清单文件路径 |
限定主机
使用 -l|--limit <pattern> 参数可将执行范围限定到特定的分组、主机或匹配模式:
./node.yml # 在所有节点上执行
./pgsql.yml -l pg-test # 仅在 pg-test 集群上执行
./pgsql.yml -l pg-* # 在所有以 pg- 开头的集群上执行
./pgsql.yml -l 10.10.10.10 # 仅在特定 IP 的主机上执行
不指定主机限制直接运行剧本可能非常危险!缺省情况下,大多数剧本会在 所有(
all) 主机上执行。务必谨慎使用!
限定任务
使用 -t|--tags <tags> 参数可仅执行带有指定标签的任务子集:
./infra.yml -t repo # 仅执行创建本地仓库的任务
./infra.yml -t repo_upstream # 仅执行添加上游仓库的任务
./node.yml -t node_pkg # 仅执行安装节点软件包的任务
./pgsql.yml -t pg_hba # 仅执行渲染 pg_hba.conf 的任务
传递变量
使用 -e|--extra-vars <key=value> 参数可在运行时覆盖变量:
./pgsql.yml -e pg_clean=true # 强制清理现有的 PG 实例
./pgsql-rm.yml -e pg_rm_pkg=false # 卸载时保留软件包
./node.yml -e '{"node_tune":"tiny"}' # 使用 JSON 格式传递变量
./pgsql.yml -e @/path/to/config.yml # 从 YAML 文件加载变量
指定配置清单
默认情况下,Ansible 会使用当前目录下的 pigsty.yml 作为配置清单。
使用 -i|--inventory <path> 参数可指定其他配置文件:
./pgsql.yml -i files/pigsty/full.yml -l pg-test
[!NOTE]
若要永久更改默认配置文件的路径,可修改
ansible.cfg中的inventory参数。
2 - 剧本
Pigsty 使用幂等的 Ansible 剧本实现管理控制。执行剧本需要将 ansible-playbook 添加到系统 PATH 中,用户需要先 安装 Ansible 才能执行剧本。
可用剧本
| 模块 | 剧本 | 功能 |
|---|---|---|
| INFRA | deploy.yml | 一键式安装 Pigsty |
| INFRA | infra.yml | 在基础设施节点上初始化 Pigsty 基础设施 |
| INFRA | infra-rm.yml | 从基础设施节点移除基础设施组件 |
| INFRA | cache.yml | 从目标节点制作离线安装包 |
| INFRA | cert.yml | 使用 Pigsty 自签名 CA 签发证书 |
| NODE | node.yml | 初始化节点,将节点配置到预期状态 |
| NODE | node-rm.yml | 从 Pigsty 中移除节点 |
| PGSQL | pgsql.yml | 初始化高可用 PostgreSQL 集群,或添加新从库 |
| PGSQL | pgsql-rm.yml | 移除 PostgreSQL 集群,或移除从库 |
| PGSQL | pgsql-db.yml | 向现有 PostgreSQL 集群添加新业务数据库 |
| PGSQL | pgsql-user.yml | 向现有 PostgreSQL 集群添加新业务用户 |
| PGSQL | pgsql-pitr.yml | 在现有 PostgreSQL 集群上执行时间点恢复(PITR) |
| PGSQL | pgsql-monitor.yml | 使用本地导出器监控远程 PostgreSQL 实例 |
| PGSQL | pgsql-migration.yml | 为现有 PostgreSQL 生成迁移手册和脚本 |
| PGSQL | slim.yml | 以最小化组件安装 Pigsty |
| REDIS | redis.yml | 初始化 Redis 集群/节点/实例 |
| REDIS | redis-rm.yml | 移除 Redis 集群/节点/实例 |
| ETCD | etcd.yml | 初始化 ETCD 集群,或添加新成员 |
| ETCD | etcd-rm.yml | 移除 ETCD 集群,或移除现有成员 |
| MINIO | minio.yml | 初始化 MinIO 集群 |
| MINIO | minio-rm.yml | 移除 MinIO 集群 |
| DOCKER | docker.yml | 在节点上安装 Docker |
| DOCKER | app.yml | 使用 Docker Compose 安装应用 |
| FERRET | mongo.yml | 在节点上安装 Mongo/FerretDB |
部署策略
deploy.yml 剧本会按照以下分组顺序协调各个专用剧本,完成完整部署:
- infra:
infra.yml(-l infra) - nodes:
node.yml - etcd:
etcd.yml(-l etcd) - minio:
minio.yml(-l minio) - pgsql:
pgsql.yml
循环依赖说明:NODE 和 INFRA 之间存在弱循环依赖:要将 NODE 注册到 INFRA,INFRA 必须已经存在;而 INFRA 模块又依赖 NODE 才能工作。 解决方法是先初始化
infra节点,然后再添加其他节点。如果希望一次性完成所有部署,使用deploy.yml即可。
安全须知
大多数剧本都是幂等的,这意味着某些部署剧本在未开启保护选项的情况下,可能会擦除现有数据库并创建新数据库。 使用
pgsql、minio和infra剧本时请特别小心。请仔细阅读文档,谨慎操作。
最佳实践
- 执行前仔细阅读剧本文档
- 发现异常时立即按 Ctrl-C 停止
- 先在非生产环境中进行测试
- 使用
-l参数限定执行主机,避免影响非目标主机 - 使用
-t参数指定特定标签,仅执行部分任务
预演模式
使用 --check --diff 选项可以预览将要进行的更改,而不实际执行:
# 预览将要进行的更改,但不实际执行
./pgsql.yml -l pg-test --check --diff
# 结合标签检查特定任务
./pgsql.yml -l pg-test -t pg_config --check --diff
3 - Nginx 管理
Pigsty 在 INFRA 节点上安装 Nginx 作为所有 Web 服务的入口,默认监听在 80/443 标准端口上。
在 Pigsty 中,你可以通过修改配置清单,让 nginx 对外提供多种服务:
- 对外暴露 Grafana、VictoriaMetrics(VMUI)、Alertmanager、VictoriaLogs 等监控组件的 Web 界面
- 提供静态文件服务(如软件仓库、文档站,网站等)
- 代理自定义的应用服务(如内部应用、数据库管理界面,Docker 应用的界面等)
- 自动签发自签名的 HTTPS 证书,或者使用 certbot 申请免费的 Let’s Encrypt 证书
- 通过不同的子域名,使用单一端口对外暴露服务
基础配置
您可以通过 infra_portal 参数定制 Nginx 的行为,
infra_portal:
home: { domain: i.pigsty }
服务器参数
基本参数
| 参数 | 说明 |
|---|---|
domain | 可选的代理域名 |
endpoint | 上游服务地址(IP:PORT 或 socket) |
path | 静态内容的本地目录 |
scheme | 协议类型(http/https/tcp/udp) |
SSL/TLS 选项
| 参数 | 说明 |
|---|---|
certbot | 启用 Let’s Encrypt 证书管理 |
cert | 自定义证书文件路径 |
key | 自定义私钥文件路径 |
高级设置
| 参数 | 说明 |
|---|---|
conf | 自定义 Nginx 配置模板 |
domains | 额外的域名列表 |
index | 启用目录列表 |
log | 自定义日志文件配置 |
websocket | 启用 WebSocket 支持 |
配置示例
静态文件与目录列表
repo: { domain: repo.pigsty.cc, path: "/www/repo", index: true }
自定义 SSL 证书
secure_app: {
domain: secure.pigsty.cc,
endpoint: "${admin_ip}:8443",
cert: "/etc/ssl/certs/custom.crt",
key: "/etc/ssl/private/custom.key"
}
TCP 流代理
pg_primary: { domain: pg.pigsty.cc, endpoint: "10.10.10.11:5432", scheme: tcp }
管理命令
./infra.yml -t nginx # 完整重新配置 Nginx
./infra.yml -t nginx_config # 重新生成配置文件
./infra.yml -t nginx_launch # 重启 Nginx 服务
./infra.yml -t nginx_cert # 重新生成 SSL 证书
域名解析
有三种方式将域名解析到 Pigsty 服务器:
- 公网域名:通过 DNS 服务商配置
- 内网 DNS 服务器:配置内部 DNS 解析
- 本地 hosts 文件:修改
/etc/hosts
本地开发时,在 /etc/hosts 中添加:
<your_public_ip_address> i.pigsty g.pigsty p.pigsty a.pigsty
HTTPS 配置
通过 nginx_sslmode 参数配置 HTTPS:
| 模式 | 说明 |
|---|---|
disable | 仅监听 HTTP(nginx_port) |
enable | 同时监听 HTTPS(nginx_ssl_port),默认签发自签名证书 |
enforce | 强制跳转到 HTTPS,所有 80 端口请求都会 301 重定向 |
对于自签名证书,有以下几种访问方式:
- 在浏览器中信任自签名 CA
- 使用浏览器安全绕过(Chrome 中输入 “thisisunsafe”)
- 为生产环境配置正规 CA 签发的证书
最佳实践
- 使用域名而非 IP:PORT 访问
- 正确配置 DNS 解析或 hosts 文件
- 为实时服务启用 WebSocket
- 生产环境部署 HTTPS
- 使用有意义的子域名组织服务
- 监控证书过期时间
- 集中化代理管理
- 利用静态文件服务托管文档
以下是 Pigsty 公开演示站点 demo.pigsty.cc 使用的 Nginx 配置: 您可以在 Nginx 上监听不同的域名,通过反向代理的方式,使用统一入口对外暴露不同的 Web 服务:
infra_portal: # domain names and upstream servers
home : { domain: home.pigsty.cc ,certbot: pigsty.demo }
grafana : { domain: demo.pigsty.cc ,endpoint: "${admin_ip}:3000", websocket: true ,certbot: pigsty.demo }
prometheus : { domain: p.pigsty.cc ,endpoint: "${admin_ip}:8428" ,certbot: pigsty.demo }
alertmanager : { domain: a.pigsty.cc ,endpoint: "${admin_ip}:9059" ,certbot: pigsty.demo }
blackbox : { endpoint: "${admin_ip}:9115" }
vmalert : { endpoint: "${admin_ip}:8880" }
postgrest : { domain: api.pigsty.cc ,endpoint: "127.0.0.1:8884" }
pgadmin : { domain: adm.pigsty.cc ,endpoint: "127.0.0.1:8885" }
pgweb : { domain: cli.pigsty.cc ,endpoint: "127.0.0.1:8886" }
bytebase : { domain: ddl.pigsty.cc ,endpoint: "127.0.0.1:8887" }
jupyter : { domain: lab.pigsty.cc ,endpoint: "127.0.0.1:8888" ,websocket: true }
gitea : { domain: git.pigsty.cc ,endpoint: "127.0.0.1:8889" ,certbot: pigsty.cc }
wiki : { domain: wiki.pigsty.cc ,endpoint: "127.0.0.1:9002" ,certbot: pigsty.cc }
noco : { domain: noco.pigsty.cc ,endpoint: "127.0.0.1:9003" ,certbot: pigsty.cc }
supa : { domain: supa.pigsty.cc ,endpoint: "10.2.82.163:8000" ,websocket: true ,certbot: pigsty.cc }
dify : { domain: dify.pigsty.cc ,endpoint: "10.2.82.163:8001" ,websocket: true ,certbot: pigsty.cc }
odoo : { domain: odoo.pigsty.cc ,endpoint: "127.0.0.1:8069" ,websocket: true ,certbot: pigsty.cc }
mm : { domain: mm.pigsty.cc ,endpoint: "10.2.82.163:8065" ,websocket: true }
web.io:
domain: en.pigsty.cc
path: "/www/web.io"
certbot: pigsty.doc
enforce_https: true
config: |
# rewrite /zh/ to /
location /zh/ {
rewrite ^/zh/(.*)$ /$1 permanent;
}
web.cc:
domain: pigsty.cc
path: "/www/web.cc"
domains: [ zh.pigsty.cc ]
certbot: pigsty.doc
config: |
# rewrite /zh/ to /
location /zh/ {
rewrite ^/zh/(.*)$ /$1 permanent;
}
repo:
domain: pro.pigsty.cc
path: "/www/repo"
index: true
certbot: pigsty.doc
更多信息,请参阅 教程:Certbot:申请与更新HTTPS证书
4 - 软件仓库
Pigsty 支持创建和管理本地 APT/YUM 软件仓库,用于在离线环境中部署或加速软件包安装。
快速开始
向本地仓库添加软件包:
- 将软件包添加到
repo_packages(默认软件包) - 将软件包添加到
repo_extra_packages(额外软件包) - 执行构建命令:
./infra.yml -t repo_build # 从上游构建本地仓库
./node.yml -t node_repo # 刷新节点仓库缓存
软件包别名
Pigsty 预定义了常用的软件包组合,方便批量安装:
EL 系统(RHEL/CentOS/Rocky)
| 别名 | 说明 |
|---|---|
node-bootstrap | Ansible、Python3 工具、SSH 相关 |
infra-package | Nginx、etcd、HAProxy、监控导出器、MinIO 等 |
pgsql-utility | Patroni、pgBouncer、pgBackRest、PG 工具 |
pgsql | 完整 PostgreSQL(服务端、客户端、扩展) |
pgsql-mini | 最小化 PostgreSQL 安装 |
Debian/Ubuntu 系统
| 别名 | 说明 |
|---|---|
node-bootstrap | Ansible、开发工具 |
infra-package | 基础设施组件(使用 Debian 命名规范) |
pgsql-client | PostgreSQL 客户端 |
pgsql-server | PostgreSQL 服务端及相关包 |
剧本任务
主要任务
| 任务 | 说明 |
|---|---|
repo | 从互联网或离线包创建本地仓库 |
repo_build | 如不存在则从上游构建 |
repo_upstream | 添加上游仓库文件 |
repo_pkg | 下载软件包及依赖 |
repo_create | 创建/更新 YUM 或 APT 仓库 |
repo_nginx | 启动 Nginx 文件服务器 |
完整任务列表
./infra.yml -t repo_dir # 创建本地软件仓库目录
./infra.yml -t repo_check # 检查本地仓库是否存在
./infra.yml -t repo_prepare # 直接使用已有仓库
./infra.yml -t repo_build # 从上游构建仓库
./infra.yml -t repo_upstream # 添加上游仓库
./infra.yml -t repo_remove # 删除现有仓库文件
./infra.yml -t repo_add # 添加仓库到系统目录
./infra.yml -t repo_url_pkg # 从互联网下载包
./infra.yml -t repo_cache # 创建元数据缓存
./infra.yml -t repo_boot_pkg # 安装引导包
./infra.yml -t repo_pkg # 下载包及依赖
./infra.yml -t repo_create # 创建本地仓库
./infra.yml -t repo_use # 添加新建仓库到系统
./infra.yml -t repo_nginx # 启动 Nginx 文件服务器
常用操作
添加新软件包
# 1. 配置上游仓库
./infra.yml -t repo_upstream
# 2. 下载软件包及依赖
./infra.yml -t repo_pkg
# 3. 构建本地仓库元数据
./infra.yml -t repo_create
刷新节点仓库
./node.yml -t node_repo # 刷新所有节点的仓库缓存
完整重建仓库
./infra.yml -t repo # 从互联网或离线包创建仓库
5 - 域名管理
使用域名代替 IP 地址访问 Pigsty 的各项 Web 服务。
快速开始
将以下静态解析记录添加到 /etc/hosts:
10.10.10.10 i.pigsty g.pigsty p.pigsty a.pigsty
将 IP 地址替换为实际 Pigsty 节点的 IP。
为什么使用域名
- 比 IP 地址更易于记忆
- 灵活指向不同 IP
- 通过 Nginx 统一管理服务
- 支持 HTTPS 加密
- 防止某些地区的 ISP 劫持
- 允许通过代理访问内部绑定的服务
DNS 机制
DNS 协议:将域名解析为 IP 地址。多个域名可以指向同一个 IP。
HTTP 协议:使用 Host 头将请求路由到同一端口(80/443)上的不同站点。
默认域名
Pigsty 预定义了以下默认域名:
| 域名 | 服务 | 端口 | 用途 |
|---|---|---|---|
i.pigsty | Nginx | 80/443 | 默认首页、本地仓库与统一入口 |
g.pigsty | Grafana | 3000 | 监控与可视化 |
p.pigsty | VictoriaMetrics | 8428 | VMUI/PromQL 入口 |
a.pigsty | AlertManager | 9059 | 告警路由 |
解析方式
本地静态解析
在客户端机器的 /etc/hosts 中添加条目:
# Linux/macOS
sudo vim /etc/hosts
# Windows
notepad C:\Windows\System32\drivers\etc\hosts
添加内容:
10.10.10.10 i.pigsty g.pigsty p.pigsty a.pigsty
内网动态解析
在内部 DNS 服务器上配置这些域名记录。
公网域名
购买域名并添加 DNS A 记录指向公网 IP。
HTTPS 证书
Pigsty 默认使用自签名证书。可选方案包括:
- 忽略警告,使用 HTTP
- 信任自签名 CA 证书
- 使用真实 CA 或通过 Certbot 获取免费公网域名证书
详见 CA 与证书 文档。
扩展域名
Pigsty 扩展预留了以下域名:
| 域名 | 用途 |
|---|---|
adm.pigsty | 管理界面 |
ddl.pigsty | DDL 管理 |
cli.pigsty | 命令行界面 |
api.pigsty | API 服务 |
lab.pigsty | 实验环境 |
git.pigsty | Git 服务 |
wiki.pigsty | Wiki 文档 |
noco.pigsty | NocoDB |
supa.pigsty | Supabase |
dify.pigsty | Dify AI |
odoo.pigsty | Odoo ERP |
mm.pigsty | Mattermost |
6 - 模块管理
本文介绍 INFRA 模块的日常管理操作,包括安装、卸载、扩容、以及各组件的管理维护。
安装 Infra 模块
使用 infra.yml 剧本在 infra 分组上安装 INFRA 模块:
./infra.yml # 在 infra 分组上安装 INFRA 模块
卸载 Infra 模块
使用 infra-rm.yml 剧本从 infra 分组上卸载 INFRA 模块:
./infra-rm.yml # 从 infra 分组上卸载 INFRA 模块
扩容 Infra 模块
在配置清单中为新节点分配 infra_seq 并加入 infra 分组:
all:
children:
infra:
hosts:
10.10.10.10: { infra_seq: 1 } # 原有节点
10.10.10.11: { infra_seq: 2 } # 新节点
使用限制选项 -l 仅在新节点上执行剧本:
./infra.yml -l 10.10.10.11 # 在新节点上安装 INFRA 模块
管理本地软件仓库
本地软件仓库相关的管理任务:
./infra.yml -t repo # 从互联网或离线包创建仓库
./infra.yml -t repo_upstream # 添加上游仓库
./infra.yml -t repo_pkg # 下载包及依赖
./infra.yml -t repo_create # 创建本地 yum/apt 仓库
完整子任务列表:
./infra.yml -t repo_dir # 创建本地软件仓库
./infra.yml -t repo_check # 检查本地软件仓库是否存在
./infra.yml -t repo_prepare # 直接使用已有仓库
./infra.yml -t repo_build # 从上游构建仓库
./infra.yml -t repo_upstream # 添加上游仓库
./infra.yml -t repo_remove # 删除现有仓库文件
./infra.yml -t repo_add # 添加仓库到系统目录
./infra.yml -t repo_url_pkg # 从互联网下载包
./infra.yml -t repo_cache # 创建元数据缓存
./infra.yml -t repo_boot_pkg # 安装引导包
./infra.yml -t repo_pkg # 下载包及依赖
./infra.yml -t repo_create # 创建本地仓库
./infra.yml -t repo_use # 添加新建仓库到系统
./infra.yml -t repo_nginx # 启动 nginx 文件服务器
管理 Nginx
Nginx 相关的管理任务:
./infra.yml -t nginx # 重置 Nginx 组件
./infra.yml -t nginx_index # 重新渲染首页
./infra.yml -t nginx_config,nginx_reload # 重新渲染配置并重载
申请 HTTPS 证书:
./infra.yml -t nginx_certbot,nginx_reload -e certbot_sign=true
管理基础设施组件
基础设施各组件的管理命令:
./infra.yml -t infra # 配置基础设施
./infra.yml -t infra_env # 配置环境变量
./infra.yml -t infra_pkg # 安装软件包
./infra.yml -t infra_user # 设置操作系统用户
./infra.yml -t infra_cert # 颁发证书
./infra.yml -t dns # 配置 DNSMasq
./infra.yml -t nginx # 配置 Nginx
./infra.yml -t victoria # 配置 VictoriaMetrics/Logs/Traces
./infra.yml -t alertmanager # 配置 AlertManager
./infra.yml -t blackbox # 配置 Blackbox Exporter
./infra.yml -t grafana # 配置 Grafana
./infra.yml -t infra_register # 注册到 VictoriaMetrics/Grafana
常用维护命令:
./infra.yml -t nginx_index # 重新渲染首页
./infra.yml -t nginx_config,nginx_reload # 重新配置并重载
./infra.yml -t vmetrics_config,vmetrics_launch # 重新生成 VictoriaMetrics 配置并重启
./infra.yml -t vlogs_config,vlogs_launch # 更新 VictoriaLogs 配置
./infra.yml -t grafana_plugin # 下载 Grafana 插件
7 - CA 与证书
Pigsty 默认使用自签名证书颁发机构 (CA) 进行内部 SSL/TLS 加密。本文档包含:
- 自签名 CA:默认的 PKI 基础设施
- 签发证书:使用
cert.yml签发额外证书 - 信任 CA 证书:在客户端机器上安装 CA
- Let’s Encrypt:为公网服务使用真实证书
自签名 CA
Pigsty 在基础设施初始化 (infra.yml) 时自动创建自签名 CA。该 CA 用于签发以下证书:
- PostgreSQL 服务器/客户端 SSL
- Patroni REST API
- etcd 集群通信
- MinIO 集群通信
- Nginx HTTPS(备用)
- 基础设施服务
PKI 目录结构
files/pki/
├── ca/
│ ├── ca.key # CA 私钥(务必保管好!)
│ └── ca.crt # CA 证书
├── csr/ # 证书签名请求
├── misc/ # 杂项证书(cert.yml 输出)
├── etcd/ # ETCD 证书
├── pgsql/ # PostgreSQL 证书
├── minio/ # MinIO 证书
├── infra/ # 基础设施证书
├── nginx/ # Nginx 证书
└── mongo/ # FerretDB 证书
CA 变量
| 变量 | 默认值 | 说明 |
|---|---|---|
ca_create | true | 如果不存在则创建 CA,否则中止 |
ca_cn | pigsty-ca | CA 证书通用名称 |
cert_validity | 7300d | 签发证书的默认有效期 |
证书有效期
| 证书类型 | 有效期 | 控制参数 |
|---|---|---|
| CA 证书 | 100 年 | 硬编码(36500 天) |
| 服务器/客户端 | 20 年 | cert_validity(7300d) |
| Nginx HTTPS | ~1 年 | nginx_cert_validity(397d) |
注意:浏览器厂商限制超过 398 天的证书信任。Nginx 使用较短有效期以保证浏览器兼容性。
使用外部 CA
如需使用企业自有 CA 而非自动生成的 CA:
在配置中设置
ca_create: false在运行 playbook 之前放置 CA 文件:
mkdir -p files/pki/ca cp /path/to/your/ca.key files/pki/ca/ca.key cp /path/to/your/ca.crt files/pki/ca/ca.crt chmod 600 files/pki/ca/ca.key chmod 644 files/pki/ca/ca.crt运行
./infra.yml
备份 CA 文件
CA 私钥至关重要,请安全备份:
# 带时间戳备份
tar -czvf pigsty-ca-$(date +%Y%m%d).tar.gz files/pki/ca/
警告:如果丢失 CA 私钥,由其签发的所有证书都将无法验证。您需要重新生成所有内容。
签发证书
使用 cert.yml 签发由 Pigsty CA 签名的额外证书。
基本用法
# 为数据库用户签发证书(客户端证书)
./cert.yml -e cn=dbuser_dba
# 为监控用户签发证书
./cert.yml -e cn=dbuser_monitor
默认情况下,证书生成在 files/pki/misc/<cn>.{key,crt}。
参数说明
| 参数 | 默认值 | 说明 |
|---|---|---|
cn | pigsty | 通用名称(必填) |
san | [DNS:localhost, IP:127.0.0.1] | 主题备用名称 |
org | pigsty | 组织名称 |
unit | pigsty | 组织单位名称 |
expire | 7300d | 证书有效期(20 年) |
key | files/pki/misc/<cn>.key | 私钥输出路径 |
crt | files/pki/misc/<cn>.crt | 证书输出路径 |
高级示例
# 签发带自定义 SAN(DNS 和 IP)的证书
./cert.yml -e cn=myservice \
-e '{"san":["DNS:myservice.local","DNS:myservice","IP:10.10.10.10"]}'
# 签发自定义有效期(10 年)的证书
./cert.yml -e cn=shortlived -e expire=3650d
# 签发到自定义路径
./cert.yml -e cn=custom \
-e key=/tmp/custom.key \
-e crt=/tmp/custom.crt
# 签发带自定义组织的证书
./cert.yml -e cn=external \
-e org="My Company" \
-e unit="IT Department"
使用场景
PostgreSQL 客户端证书
用于 SSL 客户端认证(pg_hba.conf 中的 cert 认证方式):
# 为 DBA 用户签发证书
./cert.yml -e cn=dbuser_dba
# 复制到客户端机器
scp files/pki/misc/dbuser_dba.{key,crt} user@client:~/.postgresql/
scp files/pki/ca/ca.crt user@client:~/.postgresql/root.crt
# 使用客户端证书连接
psql "host=pg-test port=5432 dbname=postgres user=dbuser_dba sslmode=verify-full sslcert=~/.postgresql/dbuser_dba.crt sslkey=~/.postgresql/dbuser_dba.key sslrootcert=~/.postgresql/root.crt"
服务间 TLS
用于需要双向 TLS 的内部服务:
./cert.yml -e cn=myapp -e '{"san":["DNS:myapp.service.local","IP:10.10.10.50"]}'
信任 CA 证书
在客户端机器上信任自签名 CA:
Linux (Debian/Ubuntu)
sudo cp files/pki/ca/ca.crt /usr/local/share/ca-certificates/pigsty-ca.crt
sudo update-ca-certificates
Linux (RHEL/Rocky/Alma)
sudo cp files/pki/ca/ca.crt /etc/pki/ca-trust/source/anchors/pigsty-ca.crt
sudo update-ca-trust
macOS
sudo security add-trusted-cert -d -r trustRoot \
-k /Library/Keychains/System.keychain files/pki/ca/ca.crt
Windows
Import-Certificate -FilePath files\pki\ca\ca.crt -CertStoreLocation Cert:\LocalMachine\Root
从 Nginx 下载
CA 证书也可通过 Nginx 在 http://<infra_ip>/ca.crt 获取:
curl -o ca.crt http://10.10.10.10/ca.crt
Let’s Encrypt
对于公网服务,您可以通过 Certbot 使用 Let’s Encrypt 的真实证书。
前置条件
- 拥有公网域名
- DNS 记录指向服务器的公网 IP
- Nginx 已正确配置
- 80 和 443 端口可访问
第一步:域名配置
在 infra_portal 中配置服务域名:
infra_portal:
home: { domain: pigsty.cc }
grafana: { domain: g.pigsty.cc, endpoint: "${admin_ip}:3000", websocket: true }
prometheus: { domain: p.pigsty.cc, endpoint: "${admin_ip}:8428" }
alertmanager: { domain: a.pigsty.cc, endpoint: "${admin_ip}:9059" }
第二步:DNS 配置
通过 A 记录将所有域名指向服务器的公网 IP:
nslookup g.pigsty.cc
dig +short g.pigsty.cc
第三步:申请证书
交互式方式:
certbot --nginx -d pigsty.cc -d g.pigsty.cc -d p.pigsty.cc -d a.pigsty.cc
非交互式方式:
certbot --nginx --agree-tos --email [email protected] -n \
-d pigsty.cc -d g.pigsty.cc -d p.pigsty.cc -d a.pigsty.cc
第四步:Nginx 配置
在 portal 条目中添加 certbot: true 参数,然后重新生成配置:
./infra.yml -t nginx_config,nginx_launch
第五步:自动续期
测试续期(预演模式):
certbot renew --dry-run
设置 cron 定时任务(每月 1 日凌晨 2 点):
0 2 1 * * certbot renew --quiet
或启用 systemd 定时器:
systemctl enable certbot.timer
管理命令
Certbot 命令
| 命令 | 说明 |
|---|---|
certbot certificates | 列出所有证书 |
certbot renew --cert-name domain.com | 续期指定证书 |
certbot delete --cert-name domain.com | 删除证书 |
certbot revoke --cert-path /path/to/cert.pem | 吊销证书 |
OpenSSL 命令
# 查看证书详情
openssl x509 -in files/pki/ca/ca.crt -text -noout
# 查看证书过期时间
openssl x509 -in files/pki/pgsql/pg-meta-1.crt -enddate -noout
# 验证证书是否由 CA 签发
openssl verify -CAfile files/pki/ca/ca.crt files/pki/pgsql/pg-meta-1.crt
# 检查证书链
openssl s_client -connect 10.10.10.10:5432 -starttls postgres </dev/null
故障排查
| 问题 | 解决方案 |
|---|---|
| 证书过期 | 重新运行 playbook 重新生成,或使用 cert.yml |
| CA 不被信任 | 在客户端安装 CA 证书(参见信任 CA 章节) |
| 域名无法访问 | 验证 DNS 传播是否完成 |
| 端口 80 被阻止 | 确保 Let’s Encrypt 验证时端口 80 开放 |
| 请求频率限制 | 避免短时间内多次申请 Let’s Encrypt 证书 |
| 权限被拒绝 | 检查文件权限(密钥:0600,证书:0644) |
最佳实践
- 备份 CA 密钥:将
files/pki/ca/ca.key安全地离线存储 - 使用适当的有效期:nginx 用短期(浏览器兼容),内部服务用长期
- 轮换证书:定期重新运行 playbook 刷新证书
- 监控过期:设置证书过期告警
- 公网用 Let’s Encrypt:内部用自签名,公网服务用真实证书
- 记录配置:跟踪哪些服务使用哪些证书