摘要(Excerpt)

本文记录一次数据库巡检自动化实战:使用 NetBox 管理资产和数据库字段,Ansible 执行 MySQL 只读巡检,GitLab CI 负责任务触发和报告归档,Vault Database Secrets Engine 动态下发临时数据库账号。文章重点介绍整体架构、关键代码、Vault 授权模型、GitLab CI 集成,以及真实排错过程中踩到的变量优先级、权限 403、客户端路径等问题。

背景:数据库巡检最怕两件事

在日常运维里,数据库巡检听起来不复杂,无非是查版本、连接数、慢查询、业务库容量、运行时长等指标。但真正落地到生产环境,会马上遇到几个现实问题。

第一,数据库主机不一定都在同一个环境,资产信息散落在 CMDB、Excel 或人工记录里。哪些主机是 MySQL,哪个端口,是否走 socket,谁来维护这些信息,都容易变成隐患。

第二,巡检账号怎么管。很多团队一开始会把 MySQL 账号密码写到 Ansible Vault、CI 变量甚至脚本里。短期看能跑,长期看就会遇到密码轮换困难、权限过大、泄露后难追踪的问题。

第三,巡检要能被审计。谁触发的,跑了哪些主机,哪些成功、哪些失败,报告在哪里留档,这些都需要形成闭环。

这次实践的目标就是把这几件事串起来:

用 NetBox 管资产,用 GitLab CI 做调度入口,用 Vault 动态下发数据库只读账号,用 Ansible 执行巡检并生成报告。

最终链路如下:

NetBox 标记 MySQL 主机
  -> Ansible inventory 生成 db_mysql 分组和变量
  -> GitLab CI 用 DB_INSPECT_VAULT_* 登录 Vault
  -> Vault 返回短期 VAULT_TOKEN
  -> Ansible 用 VAULT_TOKEN 读取 database/creds/<vault_database_role>
  -> Vault 创建动态只读 MySQL 账号
  -> Ansible 在目标主机本地执行 mysql 巡检 SQL
  -> 删除临时配置文件
  -> 吊销 Vault lease
  -> 汇总 JSON/Markdown 报告
  -> GitLab artifact 留档

总体架构设计

这套方案拆成四层。

资产层:NetBox

NetBox 负责维护哪些主机是数据库主机,以及数据库相关元数据,例如 database_engine、database_port、database_socket、vault_database_role。Ansible 不再靠人工维护一份单独的数据库主机清单。

执行层:Ansible

Ansible 负责登录目标主机,在目标主机本地执行 mysql 客户端命令。这里的本地是指 MySQL 主机自己,所以报告里看到 127.0.0.1:3306 是正常的,它表示 Ansible SSH 到数据库主机后,在那台机器上连接本机 MySQL。

凭据层:Vault

Vault Database Secrets Engine 保存每台数据库的管理连接配置,并在巡检时动态创建临时只读账号。Ansible 不保存 MySQL 固定密码,也不在报告里输出动态密码。

调度与归档层:GitLab CI

GitLab CI 负责触发任务、用 AppRole 登录 Vault、运行 playbook,并把 JSON 和 Markdown 报告作为 artifact 保存。

NetBox:用字段驱动数据库分组

首先在 NetBox 里定义数据库相关字段。最终需要的字段如下:

  • database_engine:数据库类型,例如 mysql,为空表示非数据库主机。
  • database_port:MySQL 端口,例如 3306。
  • database_socket:本机 socket 路径,不填则走 TCP。
  • vault_database_role:Vault Database Secrets Engine 的动态账号 role。

Ansible 的 NetBox 动态 inventory 中,通过 compose 把这些字段转成主机变量,通过 keyed_groups 自动生成数据库分组。

plugin: netbox.netbox.nb_inventory
validate_certs: false

config_context: false
interfaces: true
fetch_all: true

query_filters:
  - status: active

compose:
  ansible_host: primary_ip4.address.split('/')[0]
  ansible_connection: "'winrm' if custom_fields.login_protocol == 'winrm' else 'ssh'"
  login_protocol: custom_fields.login_protocol
  maintenance_window: custom_fields.maintenance_window
  database_engine: custom_fields.database_engine | default('', true)
  db_inspect_mysql_port: custom_fields.database_port | default(3306, true)
  db_inspect_mysql_socket: custom_fields.database_socket | default('', true)
  db_inspect_vault_role: custom_fields.vault_database_role | default('mysql-readonly', true)
  allow_auto_password_change: custom_fields.allow_auto_password_change
  allow_auto_file_upload: custom_fields.allow_auto_file_upload
  allow_auto_remediation: custom_fields.allow_auto_remediation

keyed_groups:
  - key: custom_fields.environment
    prefix: env
  - key: platform.name
    prefix: os
  - key: custom_fields.business_owner
    prefix: biz
  - key: custom_fields.login_protocol
    prefix: protocol
  - key: custom_fields.database_engine | lower
    prefix: db

这段配置的关键点是:database_engine=mysql 的主机会自动进入 db_mysql 分组。后续 MySQL 巡检 playbook 默认只跑这个组。

变量优先级:一个很容易踩的坑

最初实现时,我把 db_inspect_vault_role: mysql-readonly、db_inspect_mysql_command: mysql 这类默认值放在了 playbook 的 vars/defaults.yml,再通过 vars_files 加载。

这看起来像“默认变量”,但在 Ansible 里并不是低优先级默认值。vars_files 的优先级高于 inventory 变量,会覆盖 NetBox 动态 inventory 和 host_vars 下发的值。

实际表现就是:

  • NetBox 明明下发了 db_inspect_vault_role=mysql-10-8-4-15-readonly。
  • Playbook 实际却使用 mysql-readonly。
  • Vault policy 只授权了 database/creds/mysql-10-8-4-15-readonly。
  • 最终报 403 permission denied。

最终修正方式是:把“按主机可覆盖”的默认值放到 inventory 的 group_vars/db_mysql.yml,而不是 playbook 的 vars_files。

# db_mysql 组默认变量(仅作用于 NetBox database_engine=mysql 生成的 db_mysql 组)。
#
# 这些是“按主机可覆盖”的默认值,放在 inventory group_vars,优先级低于:
#   - NetBox 动态 inventory 下发的 host 变量(custom_fields.* compose)
#   - inventories/host_vars/<host>.yml
# 因此 NetBox 字段或 host_vars 一旦设置,会自动覆盖这里的默认值。
#
# 注意:不要把这些变量放进 playbooks/05-db-ops/vars/defaults.yml,
# 因为 play 的 vars_files 优先级高于 inventory,会反过来覆盖 NetBox / host_vars。

db_inspect_mysql_host: "127.0.0.1"
db_inspect_mysql_port: 3306
db_inspect_mysql_socket: ""

db_inspect_mysql_command: mysql

db_inspect_vault_role: mysql-readonly

这次排错最大的经验是:不要把“希望被 inventory 覆盖的默认值”放进 vars_files。它不是低优先级默认值,而是会压过 inventory 的 play 变量。

Vault:用动态账号代替固定密码

Vault Database Secrets Engine 的核心是两类对象:database/config/<name> 和 database/roles/<role>。

database/config/<name> 定义 Vault 如何连接数据库,里面保存管理账号和连接地址。database/roles/<role> 定义申请动态账号时执行什么 SQL,以及账号 TTL。

单实例示例:

export VAULT_ADDR='https://vault.example.com:8200'
export VAULT_TOKEN='<admin-token>'

vault secrets enable database

vault write database/config/mysql-hcn \
  plugin_name=mysql-database-plugin \
  allowed_roles="mysql-readonly" \
  connection_url="{{username}}:{{password}}@tcp(mysql-hcn-ip:3306)/" \
  username="root" \
  password="<root-password>"

vault write database/roles/mysql-readonly \
  db_name=mysql-hcn \
  creation_statements="CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}'; GRANT SELECT, PROCESS, SHOW DATABASES, REPLICATION CLIENT ON *.* TO '{{name}}'@'%';" \
  default_ttl="30m" \
  max_ttl="2h"

这里的 db_name=mysql-hcn 不是 MySQL 里的业务库名,而是 Vault 里的连接配置名,也就是 database/config/mysql-hcn。

如果每台 MySQL 的 root/admin 密码不同,建议每台 MySQL 建独立连接配置和只读 role。

vault write database/config/mysql-10-8-4-15 \
  plugin_name=mysql-database-plugin \
  allowed_roles="mysql-10-8-4-15-readonly" \
  connection_url="{{username}}:{{password}}@tcp(10.8.4.15:3306)/" \
  username="vault_admin" \
  password="<10.8.4.15-vault-admin-password>"

vault write database/roles/mysql-10-8-4-15-readonly \
  db_name=mysql-10-8-4-15 \
  creation_statements="CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}'; GRANT SELECT, PROCESS, SHOW DATABASES, REPLICATION CLIENT ON *.* TO '{{name}}'@'%';" \
  default_ttl="30m" \
  max_ttl="2h"

NetBox 中对应主机填写:

vault_database_role: mysql-10-8-4-15-readonly

这样 Ansible 会请求:

GET /v1/database/creds/mysql-10-8-4-15-readonly

Vault 创建临时 MySQL 用户并返回 username、password 和 lease_id。

Vault AppRole:CI 只拿最小权限

数据库巡检使用独立的 AppRole,例如 ansible-db-inspector,不要复用其他运维任务的 AppRole。

Policy 示例:

# 单实例或默认 role。
path "database/creds/mysql-readonly" {
  capabilities = ["read"]
}

# 多 MySQL 实例独立 role 时,可按命名规范授权全部 mysql-* 动态账号 role。
path "database/creds/mysql-*" {
  capabilities = ["read"]
}

# 后续扩展 Oracle、PostgreSQL 时,也可以继续追加对应 role。
path "database/creds/oracle-readonly" {
  capabilities = ["read"]
}

path "sys/leases/revoke" {
  capabilities = ["update"]
}

写入 policy 并创建 AppRole:

vault policy write ansible-db-inspector /tmp/ansible-db-inspector.hcl

vault write auth/approle/role/ansible-db-inspector \
  token_policies="ansible-db-inspector" \
  token_ttl="1h" \
  token_max_ttl="2h" \
  secret_id_ttl="0" \
  secret_id_num_uses="0"

获取 role_id 和 secret_id 后,保存到 GitLab CI/CD Variables:

vault read auth/approle/role/ansible-db-inspector/role-id
vault write -f auth/approle/role/ansible-db-inspector/secret-id

GitLab 变量建议如下:

  • VAULT_ADDR:Vault 地址。
  • DB_INSPECT_VAULT_ROLE_ID:数据库巡检 AppRole 的 role_id。
  • DB_INSPECT_VAULT_SECRET_ID:数据库巡检 AppRole 的 secret_id。
  • DB_INSPECT_VAULT_APPROLE_AUTH_PATH:可选,数据库巡检专用 AppRole mount。
  • VAULT_CACERT 或 VAULT_SKIP_VERIFY:Vault HTTPS 证书配置。

GitLab CI:先换 Token,再跑 Ansible

GitLab CI job 的关键逻辑是:用 DB_INSPECT_VAULT_ROLE_ID 和 DB_INSPECT_VAULT_SECRET_ID 登录 Vault,换取短期 VAULT_TOKEN,再启动 ansible-playbook。

mysql_db_inspection:
  stage: inspect
  needs: []
  resource_group: mysql-db-inspection
  timeout: 2h
  script:
    - |
      report_dir="reports/db-ops/mysql-inspection/gitlab-${CI_PIPELINE_ID}-${CI_JOB_ID}"
      ansible_limit=""
      mkdir -p ci_artifacts/mysql-inspection

      if [ -z "${VAULT_ADDR:-}" ]; then
        echo "ERROR: VAULT_ADDR is required"
        exit 1
      fi

      if [ -z "${DB_INSPECT_VAULT_ROLE_ID:-}" ]; then
        echo "ERROR: DB_INSPECT_VAULT_ROLE_ID is required"
        exit 1
      fi

      if [ -z "${DB_INSPECT_VAULT_SECRET_ID:-}" ]; then
        echo "ERROR: DB_INSPECT_VAULT_SECRET_ID is required"
        exit 1
      fi

      db_inspect_vault_approle_auth_path="${DB_INSPECT_VAULT_APPROLE_AUTH_PATH:-${VAULT_APPROLE_AUTH_PATH:-approle}}"

      login_payload="$(python3 - <<'PY'
      import json
      import os

      print(json.dumps({
          "role_id": os.environ["DB_INSPECT_VAULT_ROLE_ID"],
          "secret_id": os.environ["DB_INSPECT_VAULT_SECRET_ID"],
      }))
      PY
      )"

      login_resp="$(curl -sS --request POST \
        --data "$login_payload" \
        "${VAULT_ADDR%/}/v1/auth/${db_inspect_vault_approle_auth_path}/login")"

      export VAULT_TOKEN="$(python3 -c '
      import json
      import sys

      resp = json.load(sys.stdin)
      errors = resp.get("errors")
      if errors:
          raise SystemExit("Vault AppRole login failed: " + "; ".join(map(str, errors)))
      token = resp.get("auth", {}).get("client_token")
      if not token:
          raise SystemExit("Vault AppRole login response did not contain auth.client_token")
      print(token)
      ' <<< "$login_resp")"

      ansible-playbook -i "$ANSIBLE_INVENTORY" "$DB_INSPECT_PLAYBOOK" \
        -e "db_inspect_report_dir=${report_dir}"
  artifacts:
    name: "mysql-inspection-${CI_PIPELINE_ID}-${CI_JOB_ID}"
    when: always
    expire_in: 30 days
    paths:
      - ci_artifacts/mysql-inspection/

实际项目里还包含 limit、extra vars、报告复制和 JSON 汇总判断。核心思想不变:CI 只负责换取短期 Vault token,真正数据库密码由 Vault 动态生成。

Ansible Playbook:只跑 db_mysql 分组

主 playbook 默认只巡检 db_mysql:

- name: MySQL database inspection with Vault dynamic credentials
  hosts: "{{ db_inspect_hosts | default('db_mysql') }}"
  gather_facts: true
  become: false
  ignore_unreachable: true
  any_errors_fatal: false
  max_fail_percentage: 100
  vars_files:
    - vars/defaults.yml

  pre_tasks:
    - name: Skip hosts not marked as MySQL database in NetBox
      ansible.builtin.meta: end_host
      vars:
        _db_engine: "{{ database_engine | default(custom_fields.database_engine | default('')) | lower }}"
      when: _db_engine not in (db_inspect_database_engines | map('lower') | list)

  tasks:
    - name: Run MySQL inspection
      ansible.builtin.include_tasks: tasks/mysql_inspection.yml

这里有两层保护:第一层是 inventory 自动生成 db_mysql 分组,第二层是 playbook 再检查 database_engine。即使有人手工扩大了 hosts,非 MySQL 主机也会被跳过。

申请动态账号并执行巡检

Ansible 使用 uri 模块调用 Vault API:

- name: Request dynamic MySQL credentials from Vault
  ansible.builtin.uri:
    url: >-
      {{
        db_inspect_vault_addr | regex_replace('/+$', '')
      }}/v1/{{ db_inspect_vault_database_mount | regex_replace('^/+', '') | regex_replace('/+$', '') }}/creds/{{
        db_inspect_vault_role | urlencode
      }}
    method: GET
    headers: >-
      {{
        {'X-Vault-Token': db_inspect_vault_token}
        | combine(
          (db_inspect_vault_namespace | default('') | trim | length > 0)
          | ternary({'X-Vault-Namespace': db_inspect_vault_namespace}, {})
        )
      }}
    status_code:
      - 200
  register: _db_vault_creds
  changed_when: false
  failed_when: false
  delegate_to: localhost
  become: false
  no_log: "{{ db_inspect_no_log }}"

拿到账号后,在目标主机写入临时 MySQL option file:

- name: Write temporary MySQL option file
  ansible.builtin.copy:
    dest: "{{ _db_mysql_defaults_file.path }}"
    mode: "0600"
    content: |
      [client]
      user={{ _db_vault_username }}
      password={{ _db_vault_password }}
  no_log: "{{ db_inspect_no_log }}"
  when: _db_mysql_defaults_file.path is defined

执行 SQL 时不把密码放在命令行参数里,而是通过 --defaults-extra-file 读取:

- name: Execute MySQL inspection queries
  ansible.builtin.command:
    argv: "{{ _db_inspect_mysql_argv + ['--execute', item.sql] }}"
  loop: "{{ db_inspect_queries }}"
  loop_control:
    label: "{{ item.name }}"
  register: _db_query_exec
  changed_when: false
  failed_when: false
  when: _db_inspect_mysql_argv is defined

巡检 SQL 包括:

  • SELECT VERSION();
  • SELECT @@hostname;
  • SHOW VARIABLES LIKE 'max_connections';
  • SHOW GLOBAL STATUS LIKE 'Threads_connected';
  • SHOW GLOBAL STATUS LIKE 'Threads_running';
  • SHOW GLOBAL STATUS LIKE 'Slow_queries';
  • 查询业务库数量和最大库容量。

临时账号如何回收

Vault 返回动态账号时会带 lease_id。巡检结束后,Ansible 会调用:

PUT /v1/sys/leases/revoke

对应任务如下:

- name: Revoke Vault database credential lease
  ansible.builtin.uri:
    url: "{{ db_inspect_vault_addr | regex_replace('/+$', '') }}/v1/sys/leases/revoke"
    method: PUT
    headers: >-
      {{
        {'X-Vault-Token': db_inspect_vault_token}
      }}
    body_format: json
    body:
      lease_id: "{{ _db_vault_lease_id }}"
    status_code:
      - 200
      - 204
  register: _db_vault_revoke
  changed_when: "_db_vault_revoke.status | default(0) in [200, 204]"
  failed_when: false
  delegate_to: localhost
  become: false
  no_log: "{{ db_inspect_no_log }}"
  when:
    - db_inspect_vault_revoke_lease | bool
    - _db_vault_lease_id | default('') | trim | length > 0

正常情况下,巡检结束立即回收。即使 revoke 因异常没有执行成功,Vault 动态账号也会按 default_ttl 到期回收,例如 30m。

报告输出与 GitLab Artifact

巡检完成后,Ansible 会汇总每台主机的结果,生成 JSON 和 Markdown 两份报告。

reports/db-ops/mysql-inspection/mysql_inspection_<timestamp>.json
reports/db-ops/mysql-inspection/mysql_inspection_<timestamp>.md

在 GitLab CI 中,这些文件会复制到:

ci_artifacts/mysql-inspection/

如果报告里有 crit 或 unreachable,job 会失败。这样做的好处是:CI 状态可以直接提醒巡检异常,但报告仍然会作为 artifact 留下来,便于排查。

踩坑与避坑指南

坑一:Vault policy 正确,但 CI 仍然 403

表现:

status=403, errors=permission denied

排查思路:

vault read auth/approle/role/ansible-db-inspector
vault write auth/approle/login role_id='<role_id>' secret_id='<secret_id>'
VAULT_TOKEN='<client_token>' vault read database/creds/mysql-10-8-4-15-readonly

如果手工读成功,说明 Vault policy 和 role 本身没问题。此时要检查 GitLab CI 变量是否使用了正确的 DB_INSPECT_VAULT_ROLE_ID 和 DB_INSPECT_VAULT_SECRET_ID,以及 Ansible 实际请求的 db_inspect_vault_role 是否被变量优先级覆盖。

坑二:vars_files 覆盖了 NetBox 和 host_vars

这是本次最大的坑。vars_files 不是低优先级默认值,它的优先级会高于 inventory 变量。

错误做法是把这些变量放进 playbook 的 vars/defaults.yml:

db_inspect_mysql_command: mysql
db_inspect_vault_role: mysql-readonly

正确做法是放进 inventories/group_vars/db_mysql.yml,让 NetBox 和 host_vars 可以覆盖它们。

如果一个变量希望被 NetBox 或 host_vars 按主机覆盖,就不要放到 playbook 的 vars_files 里。

坑三:目标主机能执行 mysql,Ansible 却找不到

在目标主机交互式登录时,mysql --version 正常。但 Ansible 非交互 SSH 可能不会加载完整 PATH。

例如目标机器实际路径是:

which mysql
/data/mysql/bin/mysql

这时可以在对应 host_vars 中指定绝对路径:

ansible_port: 22
db_inspect_mysql_command: /data/mysql/bin/mysql

坑四:报告里显示 127.0.0.1:3306,是不是连错了

不是连错。报告中的 127.0.0.1:3306 是 Ansible SSH 到目标 MySQL 主机后,在那台机器本地连接 MySQL。

Vault 创建动态账号时使用的是 database/config/<name> 里的连接地址,例如 10.8.4.15:3306。这两条链路不同:

Vault -> 10.8.4.15:3306  创建动态账号
Ansible -> SSH 到 10.8.4.15 -> 127.0.0.1:3306 执行巡检 SQL

坑五:SQL 没执行时不要误报 12 条 query failed

当 Vault 申请动态账号失败时,SQL 查询会被跳过。最初的处理逻辑把 skipped 也统计成 failed,导致报告里同时出现 Vault 失败和 12 条 SQL 失败,噪音很大。

最终处理方式是把 skipped 查询单独标记为 skipped,只在 SQL 真正执行且返回非 0 时统计为 failed。

适合扩展到 Oracle 和 PostgreSQL 吗

适合。设计时没有把 CI 变量命名成 MYSQL_*,而是使用通用的 DB_INSPECT_VAULT_*。

后续扩展 Oracle 时,可以继续复用:

  • DB_INSPECT_VAULT_ROLE_ID
  • DB_INSPECT_VAULT_SECRET_ID
  • DB_INSPECT_VAULT_APPROLE_AUTH_PATH

只需要增加新的 NetBox 字段值、Ansible playbook 和 Vault policy,例如:

path "database/creds/oracle-readonly" {
  capabilities = ["read"]
}

资产分组也可以沿用 database_engine:

database_engine=oracle -> db_oracle
database_engine=mysql  -> db_mysql

总结

这次实践的核心价值不是写了几个 SQL,而是把数据库巡检变成了一条可审计、可扩展、低凭据风险的自动化链路。

NetBox 负责资产与数据库元数据,GitLab CI 负责任务入口与报告归档,Vault 负责动态账号和最小权限授权,Ansible 负责真正执行巡检逻辑。

最终效果是:

  • 不在仓库、CI 或 Ansible 变量里保存数据库固定密码。
  • 每次巡检使用 Vault 动态只读账号。
  • 巡检结束后自动吊销 lease,异常情况下也按 TTL 回收。
  • 报告自动生成 JSON 和 Markdown,并通过 GitLab artifact 留档。
  • 通过 database_engine 和 vault_database_role 可以自然扩展到多实例、多数据库类型。

对运维自动化来说,这种设计比“写死账号密码跑脚本”多走了几步,但换来的是安全性、可维护性和审计能力的明显提升。