跳转到主要内容

这是本节的多页打印视图。 .

返回本页常规视图.

任务与教程

Pigsty 中常见的任务列表与一些主题案例教学，例如：证书签发，故障演练，性能调优，数据迁移，使用 CMDB 等。

1 - Nginx：向外代理暴露Web服务

如何在使用 Nginx 对外代理、转发、暴露 Web 服务？

Pigsty 在 INFRA节点上默认会安装 Nginx 作为 Web 服务代理。（单机安装时，本机默认也是一个 INFRA节点 ）

Nginx 是 Pigsty 所有 WebUI 类服务的访问入口，默认使用管理节点 80/443 端口。

Pigsty 提供了一个全局配置变量 infra_portal，用于配置 Nginx 的代理规则，以及对应的上游服务。

如果您直接通过端口访问 Nginx，默认访问的是 h.pigsty，即 Pigsty 文件系统首页。（/www/ 目录）。 因为 Nginx 通过同一个端口对外提供多个服务，因此必须通过域名进行区分（浏览器的 HOST 首部），所以在默认情况下，Nginx 只会对外暴露 带有 domain` 参数的

默认情况下，Nginx 除了 home （文件系统，软件源）之外，还对外暴露 grafana，prometheus，alertmanager 三项可观测性服务：

infra_portal:  # domain names and upstream servers
  home         : { domain: h.pigsty }
  grafana      : { domain: g.pigsty ,endpoint: "${admin_ip}:3000" , websocket: true }
  prometheus   : { domain: p.pigsty ,endpoint: "${admin_ip}:9090" }
  alertmanager : { domain: a.pigsty ,endpoint: "${admin_ip}:9093" }
  blackbox     : { endpoint: "${admin_ip}:9115" }
  loki         : { endpoint: "${admin_ip}:3100" }
  #minio        : { domain: sss.pigsty  ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }

如何配置 Nginx 代理？

Pigsty 自带的配置模板 demo.yml 配置文件，作为一个参考，额外对外部暴露了一些 Web 服务：

    infra_portal:                     # domain names and upstream servers
      home         : { domain: h.pigsty }
      grafana      : { domain: g.pigsty ,endpoint: "${admin_ip}:3000" , websocket: true }
      prometheus   : { domain: p.pigsty ,endpoint: "${admin_ip}:9090" }
      alertmanager : { domain: a.pigsty ,endpoint: "${admin_ip}:9093" }
      blackbox     : { endpoint: "${admin_ip}:9115" }
      loki         : { endpoint: "${admin_ip}:3100" }

      minio        : { domain: sss.pigsty  ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }
      postgrest    : { domain: api.pigsty  ,endpoint: "127.0.0.1:8884" }
      pgadmin      : { domain: adm.pigsty  ,endpoint: "127.0.0.1:8885" }
      pgweb        : { domain: cli.pigsty  ,endpoint: "127.0.0.1:8886" }
      bytebase     : { domain: ddl.pigsty  ,endpoint: "127.0.0.1:8887" }
      jupyter      : { domain: lab.pigsty  ,endpoint: "127.0.0.1:8888", websocket: true }
      gitea        : { domain: git.pigsty  ,endpoint: "127.0.0.1:8889" }
      wiki         : { domain: wiki.pigsty ,endpoint: "127.0.0.1:9002" }
      noco         : { domain: noco.pigsty ,endpoint: "127.0.0.1:9003" }
      supa         : { domain: supa.pigsty ,endpoint: "10.10.10.10:8000", websocket: true }

这里不难看出，每一条记录都有一个独一无二的 name 作为 key，一个配置字典作为 value。在配置字典中，目前有以下四个可用配置项：

  • endpoint：必填，指定上游服务的地址，可以是 IP:PORT 或者 DOMAIN:PORT。
    • 在此参数中，可以使用 ${admin_ip} 占位符，Pigsty会填入 admin_ip 的值。
  • domain：可选，指定代理的域名，如果不填写，则 Nginx 不会对外暴露此服务。
    • 对于那些需要知道 endpoint 地址，但不想对外暴露的服务（例如 Loki, Blackbox Exporter），可以不填写 domain。
  • scheme：可选，指定转发时的协议（http/https），留空则默认使用 http
    • 对于那些强制要求 HTTPS 访问的上游 Web 服务（例如 MinIO 管理界面），需要指定 scheme: https。
  • websocket：可选，指定是否开启 WebSocket，留空则默认关闭。
    • 类似 Grafana、Jupyter 等需要 WebSocket 的服务需要设置为 true 方能正常工作。

因此，如果您需要新增一个通过 Nginx 暴露的 Web 服务，首先需要在 infra_portal 中添加相应地记录，然后执行剧本生效：

./infra.yml -t nginx_config    # 重新生成 Nginx 配置文件
./infra.yml -t nginx_cert      # 重新签发自签名 HTTPS 证书，囊括新增的域名
./infra.yml -t nginx_launch    # 重启 Nginx 以使配置生效（如果您不希望出现中断，手动使用 nginx -s reload）

如果您始终通过 Pigsty 管理 Nginx 配置，也可以直接使用以下任务重新初始化 Nginx 配置：

./infra.yml -t nginx           # 直接重新初始化 Nginx 至描述的状态

Nginx相关配置参数位于：配置：INFRA - NGINX

如何通过域名访问 Nginx 代理的服务？

Nginx 通过浏览器设置的 HOST 首部中的域名，来区分不同的服务，所以默认除了软件仓库之外服务，都的您需要通过域名访问。

您可以通过 IP地址 + 端口的方式直接访问这些服务。但我们更推荐您使用域名通过 Nginx 80/443 端口代理访问所有组件。

使用域名访问 Pigsty WebUI 时，您需要配置 DNS 解析，或者修改本地的 /etc/hosts 静态解析文件，有几种典型的方式

  • 如果您的服务需要直接暴露在公网上，那么应当通过 DNS 服务商（Cloudflare，Aliyun DNS 等）解析互联网域名。注意，在这种情况下，通常您还需要修改 Pigsty 的 infra_portal 参数，因为默认的 *.pigsty 并不是一个适合公网使用的域名。

  • 如果您的服务需要在办公网共享访问，那么应当通过内网 DNS 服务商（公司内部 DNS 服务器）解析内网域名，并将其指向 Nginx 服务器所在的 IP。您可以要求网络管理员在公司内部 DNS 服务器中添加相应的解析记录，也可以要求系统的用户手工配置静态的 DNS 解析记录。

  • 如果您的服务仅供自己，或少数用户使用（例如 DBA），那么您可以要求这些用户使用静态域名解析记录。在 Linux / MacOS 系统上，修改 /etc/hosts 文件（需要 sudo 权限）或 C:\Windows\System32\drivers\etc\hosts（Windows）文件。

我们建议普通单机用户使用第三种方式，在 使用浏览器访问 Web 系统的机器上 ，添加以下解析记录：

<your_public_ip_address>  h.pigsty a.pigsty p.pigsty g.pigsty

这里的 IP 地址是安装 Pigsty 服务的 对外IP地址，然后您就可以在浏览器中通过： http://g.pigsty 这样的域名网址，访问 Pigsty 的子系统了。

其他的 Web 服务与自定义域名，也可以通过同样的方式添加。例如以下是 Pigsty 沙箱 Demo 可能用到的域名解析记录：

10.10.10.10 h.pigsty a.pigsty p.pigsty g.pigsty
10.10.10.10 api.pigsty ddl.pigsty adm.pigsty cli.pigsty lab.pigsty
10.10.10.10 supa.pigsty noco.pigsty odoo.pigsty

如何使用 HTTPS 访问 Nginx 代理的服务？

Pigsty默认使用自动生成的自签名的 CA 证书为 Nginx 启用 SSL，如果您希望使用 HTTPS 访问这些页面，而不弹窗提示"不安全"，通常有三个选择：

  • 在您的浏览器或操作系统中信任 Pigsty 自签名的 CA 证书： files/pki/ca/ca.crt
  • 如果您使用 Chrome，可以在提示不安全的窗口键入 thisisunsafe 跳过提示
  • 您可以考虑使用 Let’s Encrypt 或其他免费的 CA 证书服务，为 Pigsty Nginx 生成正式的 SSL证书。

2 - Docker：启用容器支持与配置

如何在 Pigsty 启用 Docker 容器支持？Docker 的安装部署配置，以及如何解决DockerHub被“墙”的问题

Pigsty 提供了 DOCKER 模块，但默认并不安装。您可以使用 docker.yml 剧本在指定节点上安装并启用 Docker。

./docker.yml -l <ip|group|cls>   # 在指定的节点、分组、集群上安装并启用 Docker

如何建配置代理服务器？

本文不会介绍如何“翻墙”，而是假设你已经有了一个可用的 HTTP(s) 代理服务器，应该如何配置，让 Docker 可以通过代理服务器，访问 docker hub 或 quay.io 等镜像站点：

你的代理服务器软件应该会提供一个形如：

  • http://<ip|domain>:<port> 或者 https://[user]:[pass]@<ip|domain>:<port> 的代理地址

例如，假设您使用的代理服务器配置为：

export ALL_PROXY=http://192.168.0.104:8118
export HTTP_PROXY=http://192.168.0.104:8118
export HTTPS_PROXY=http://192.168.0.104:8118
export NO_PROXY="localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"

您可以使用 curl 命令，检验代理服务器是否可以正常工作，例如成功可以访问 Google，通常说明代理服务器工作正常。

curl -x http://192.168.0.104:8118 -I http://www.google.com

如何为Docker Daemon配置代理服务器？

如果您希望 Docker 在 Pull 镜像时使用代理服务器，那么应当在 pigsty.yml 配置文件的全局变量中，指定 proxy_env 参数：

all:
  vars:
    proxy_env:                        # global proxy env when downloading packages
      no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"
      http_proxy: http://192.168.0.104:8118
      all_proxy: http://192.168.0.104:8118
      https_proxy: http://192.168.0.104:8118

那么当 Docker 剧本执行，时，这些配置会被渲染为 /etc/docker/daemon.json 中的代理配置：

{
  "proxies": {
    "http-proxy": "{{ proxy_env['http_proxy'] }}",
    "https-proxy": "{{ proxy_env['http_proxy'] }}",
    "no-proxy": "{{ proxy_env['no_proxy'] }}"
  }
}

请注意，Docker Daemon 不使用 all_proxy 参数

如果您希望手工指定代理服务器，可以选则直接修改 /etc/docker/daemon.json 中的 proxies 配置； 或者也可以修改 /lib/systemd/system/docker.service (Debian/Ubuntu) 与 /usr/lib/systemd/system/docker.service 的服务定义，在 [Service] 一节中添加环境变量声明，并重启生效：

[Service]
Environment="HTTP_PROXY=http://192.168.0.104:8118"
Environment="HTTPS_PROXY=http://192.168.0.104:8118"
Environment="NO_PROXY=localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn"

重启后生效：

systemctl restart docker

如何使用其他镜像站点？

您可以在 docker_registry_mirrors 参数中指定其他镜像站点，例如阿里云、腾讯云、清华大学等镜像站点：

[ "https://mirror.ccs.tencentyun.com" ]         # tencent cloud mirror, intranet only
["https://registry.cn-hangzhou.aliyuncs.com"]   # aliyun cloud mirror, login required

不过目前来看，所有位于中国大陆的 DockerHub 公有镜像站都已经被封禁了，建议使用代理服务器直接访问 Docker Hub

如果您需要使用其他镜像站，例如 quay.io，可以首先执行：

docker login quay.io
username #> # input your username
password #> # input your password

3 - 使用 PostgreSQL 作为 Ansible 配置清单 CMDB

使用 Pigsty v2.7 自带的清单脚本，在静态 YAML 清单与 PostgreSQL CMDB 之间切换。

Pigsty v2.7 默认从 pigsty.yml 读取 Ansible 配置清单。该版本同时提供了 三个脚本，可以将清单载入 meta 数据库的 pigsty 模式，并让 Ansible 改用动态生成的清单。

本文严格对应 v2.7.0 标签中的 bin/inventory_load、 bin/inventory_cmdb 与 bin/inventory_conf。

前置条件

默认 pg-meta 集群会通过 files/cmdb.sql 创建 CMDB 模式。请先完成 infra.yml 与 pg-meta 数据库初始化，并确认 meta 服务可访问。

默认的 ansible.cfg 包含：

[defaults]
inventory = pigsty.yml

载入 YAML 清单

bin/inventory_load 会读取 YAML 清单，并替换 pigsty.group、 pigsty.host、pigsty.group_var、pigsty.host_var 与 pigsty.global_var 中的记录。载入新清单前，应先检查或备份目标 CMDB。

bin/inventory_load                                      # 使用 $PIGSTY_HOME/pigsty.yml 与 $METADB_URL
bin/inventory_load -p files/pigsty/demo.yml             # 载入另一个 v2.7 清单
bin/inventory_load -p pigsty.yml \
  -d postgresql://dbuser_meta:[email protected]:5432/meta

脚本使用 -p|--path 指定 YAML 文件，使用 -d|--data 指定 PostgreSQL 连接串；默认值来自 PIGSTY_HOME 与 METADB_URL。

切换配置源

将 Ansible 切换到 CMDB 驱动的 inventory.sh：

bin/inventory_cmdb
ansible-inventory --list

bin/inventory_cmdb 会写入可执行的 inventory.sh，并修改 ansible.cfg 中的 inventory。生成的脚本通过 PostgreSQL meta 服务 查询 pigsty.inventory。

切回静态 pigsty.yml 清单：

bin/inventory_conf
ansible-inventory --list

这三个脚本只负责载入与切换配置源，并不会在 YAML 与 CMDB 之间提供自动 双向同步。后续修改仍应明确选择权威配置源并重新校验。

4 - 使用 Keepalived 为 Pigsty 节点集群配置二层 VIP

您可以在节点集群上绑定一个可选的 L2 VIP —— 前提条件是：集群中的所有节点都在一个二层网络中。

在节点集群（任何一个 Ansible Group，包括数据库集群定义都可以视作一个节点集群）上，启用 vip_enabled 参数，即可在节点集群上启用 Keepalived ，绑定一个2层 VIP。

proxy:
  hosts:
    10.10.10.29: { nodename: proxy-1 } # 您可以显式指定初始的 VIP 角色：MASTER / BACKUP
    10.10.10.30: { nodename: proxy-2 } # , vip_role: master }
  vars:
    node_cluster: proxy
    vip_enabled: true
    vip_vrid: 128
    vip_address: 10.10.10.99
    vip_interface: eth1

使用以下命令，刷新节点的 Keepalived 配置，并生效：

./node.yml -l proxy -t node_vip     # 首次启用 VIP
./node.yml -l proxy -t vip_refresh  # 刷新 vip 配置（例如指定 master）

5 - 使用 VIP-Manager 为 PostgreSQL 集群配置二层 VIP

您可以在 PostgreSQL 集群上绑定一个可选的 L2 VIP —— 前提条件是：集群中的所有节点都在一个二层网络中。

这个 L2 VIP 强制使用 Master - Backup 模式，Master 始终指向在数据库集群主库实例所在的节点。

这个 VIP 由 VIP-Manager 组件管理，它会从 DCS （etcd） 中直接读取由 Patroni 写入的 Leader Key，从而判断自己是否是 Master。

启用VIP

在 PostgreSQL 集群上定义 pg_vip_enabled 参数为 true，即可在集群上启用 VIP 组件。当然您也可以在全局配置中启用此配置项。

# pgsql 3 node ha cluster: pg-test
pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }   # primary instance, leader of cluster
    10.10.10.12: { pg_seq: 2, pg_role: replica }   # replica instance, follower of leader
    10.10.10.13: { pg_seq: 3, pg_role: replica, pg_offline_query: true } # replica with offline access
  vars:
    pg_cluster: pg-test           # define pgsql cluster name
    pg_users:  [{ name: test , password: test , pgbouncer: true , roles: [ dbrole_admin ] }]
    pg_databases: [{ name: test }]

    # 启用 L2 VIP
    pg_vip_enabled: true
    pg_vip_address: 10.10.10.3/24
    pg_vip_interface: eth1

请注意，pg_vip_address 必须是一个合法的 IP 地址，带有网段，且在当前二层网络中可用。

请注意，pg_vip_interface 必须是一个合法的网络接口名，并且应当是与 inventory 中使用 IPv4 地址一致的网卡。 如果集群成员的网卡名不一样，用户应当为每个实例显式指定 pg_vip_interface 参数，例如：

pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary , pg_vip_interface: eth0  }
    10.10.10.12: { pg_seq: 2, pg_role: replica , pg_vip_interface: eth1  }
    10.10.10.13: { pg_seq: 3, pg_role: replica , pg_vip_interface: ens33 }
  vars:
    pg_cluster: pg-test           # define pgsql cluster name
    pg_users:  [{ name: test , password: test , pgbouncer: true , roles: [ dbrole_admin ] }]
    pg_databases: [{ name: test }]

    # 启用 L2 VIP
    pg_vip_enabled: true
    pg_vip_address: 10.10.10.3/24
    #pg_vip_interface: eth1

使用以下命令，刷新 PG 的 vip-manager 配置并重启生效：

./pgsql.yml -t pg_vip

6 - 使用 PostgreSQL 作为 Grafana 后端数据库

使用 Pigsty v2.7 管理的 PostgreSQL 数据库替代 Grafana 默认的 SQLite 元数据存储。

Grafana 默认使用 SQLite 存储元数据。Pigsty v2.7 可以为 Grafana 置备 PostgreSQL 用户与数据库，随后再手工将 Grafana 指向该数据库。

v2.7 范围

grafana_database 与 grafana_pgurl 参数在 v2.7.0 中已经废弃。该版本的 grafana.ini.j2 不会管理 PostgreSQL 后端连接串，因此重新执行 grafana_config 任务可能 覆盖手工修改；请将此变更纳入您自己的配置管理。

置备数据库

在 PGSQL 集群定义中加入用户与数据库：

pg_users:
  - { name: dbuser_grafana, password: DBUser.Grafana, pgbouncer: true, roles: [dbrole_admin] }
pg_databases:
  - { name: grafana, owner: dbuser_grafana, revokeconn: true }

对于现有 pg-meta 集群，使用 v2.7 自带脚本创建：

bin/pgsql-user pg-meta dbuser_grafana
bin/pgsql-db   pg-meta grafana
psql postgres://dbuser_grafana:DBUser.Grafana@meta:5436/grafana -c \
  'CREATE TABLE t(); DROP TABLE t;'

如果要新建专用集群，请在清单中定义同样的对象，然后执行：

bin/pgsql-add pg-grafana

这些命令分别对应 pgsql-user.yml、 pgsql-db.yml 与 pgsql.yml。

配置 Grafana

切换后端前应先备份原有 Grafana 元数据。随后修改 /etc/grafana/grafana.ini 的 [database] 段：

[database]
type = postgres
url = postgres://dbuser_grafana:DBUser.Grafana@meta:5436/grafana
ssl_mode = disable

确认连接可用后重启 Grafana：

systemctl restart grafana-server

Grafana 启动时会自行执行元数据迁移。指向一个新的空数据库并不会自动 复制原 SQLite 数据库中的面板与数据源。

恢复面板与数据源

Pigsty v2.7 将面板定义与加载脚本放在 files/grafana：

cd ~/pigsty/files/grafana
./grafana.py init

如果没有使用默认 Grafana 凭据，可通过 GRAFANA_ENDPOINT、 GRAFANA_USERNAME 与 GRAFANA_PASSWORD 环境变量传入。

使用 v2.7 任务，将 pg_databases 中声明的数据库注册为 Grafana PostgreSQL 数据源：

./pgsql.yml -t register_grafana

该命令调用 roles/pgsql/tasks/register_grafana.yml， 默认使用监控用户；只有数据库将 register_datasource 显式设为 false 时才会跳过注册。

7 - 使用 TimescaleDB + Promscale 存储 Prometheus 时序指标数据

您可以通过 Promscale，使用TimescaleDB持久化Prometheus指标数据。

虽然这并不是推荐的行为，但这是了解Pigsty部署系统使用方式的好机会。

注意，使用 Promscale 存储 Prometheus 指标占用的存储空间大约是 Prometheus 的 4 倍，但是可以使用 SQL 来查询分析 Prometheus 监控指标。

准备Postgres数据库 

vi pigsty.yml # 取消注释DB/User定义：dbuser_prometheus  prometheus

pg_databases:                           # define business users/roles on this cluster, array of user definition
  - { name: prometheus, owner: dbuser_prometheus , revokeconn: true, comment: prometheus primary database }
pg_users:                           # define business users/roles on this cluster, array of user definition
  - {name: dbuser_prometheus , password: DBUser.Prometheus ,pgbouncer: true , createrole: true,  roles: [dbrole_admin], comment: admin user for prometheus database }

创建 Prometheus 业务数据库与业务用户。

bin/pgsql-user  pg-meta  dbuser_prometheus
bin/pgsql-db    pg-meta  prometheus

检查数据库可用性并创建扩展

psql postgres://dbuser_prometheus:[email protected]:5432/prometheus -c 'CREATE EXTENSION timescaledb;'

配置Promscale

在元节点上执行以下命令安装 promscale

yum install -y promscale

如果默认软件包中没有，可以直接下载：

wget https://github.com/timescale/promscale/releases/download/0.6.1/promscale_0.6.1_Linux_x86_64.rpm
sudo rpm -ivh promscale_0.6.1_Linux_x86_64.rpm

编辑 promscale 的配置文件 /etc/sysconfig/promscale.conf

PROMSCALE_DB_HOST="127.0.0.1"
PROMSCALE_DB_NAME="prometheus"
PROMSCALE_DB_PASSWORD="DBUser.Prometheus"
PROMSCALE_DB_PORT="5432"
PROMSCALE_DB_SSL_MODE="disable"
PROMSCALE_DB_USER="dbuser_prometheus"

最后启动promscale，它会访问安装有 timescaledb 的数据库实例，并创建所需的schema

# launch
cat /usr/lib/systemd/system/promscale.service
systemctl start promscale && systemctl status promscale

配置Prometheus

Prometheus可以使用Remote Write/ Remote Read的方式，通过Promscale，使用Postgres作为远程存储。

编辑Prometheus配置文件：

vi /etc/prometheus/prometheus.yml

添加以下记录：

remote_write:
  - url: "http://127.0.0.1:9201/write"
remote_read:
  - url: "http://127.0.0.1:9201/read"

重启Prometheus后，监控数据即可放入Postgres中。

systemctl restart prometheus