最近，一台部署在 Azure 上的 Linux 服务器突然出现 CPU 持续 100% 的情况。排查后发现，服务器上存在一个以 postgres 用户身份运行的恶意程序，并通过 cron 定时任务维持运行。

这台服务器上的 PostgreSQL：

• 没有通过 Azure NSG 向公网开放 5432；
• 没有被当前业务使用；
• 业务实际使用的是本机 MySQL；
• 但 PostgreSQL 服务仍然安装并运行；
• 系统中保留了 postgres 用户、主目录、cron 和历史脚本。

这次事件说明：

PostgreSQL 没有向公网开放，并不代表服务器上与 PostgreSQL 相关的组件完全没有风险。

需要特别说明的是，目前的证据只能证明恶意程序利用了 postgres 操作系统用户及其目录进行持久化，不能证明攻击者一定是通过 PostgreSQL 的 5432 端口进入服务器的。初始入口也可能是历史配置、SSH、Web 应用、容器、旧镜像或其他漏洞。

如果生产环境确实需要 PostgreSQL，但没有必须自建数据库服务器的特殊要求，建议优先使用：

Azure Database for PostgreSQL，并通过私有网络访问，关闭公共网络入口。

这样可以减少自建数据库所带来的操作系统用户、SSH、cron、systemd、补丁、备份和主机入侵等风险。

发现问题：服务器 CPU 持续占满

最初是在服务器上执行 htop 时发现异常。

从截图中可以看到：

• 服务器共有 4 个 CPU 核心；
• 4 个核心全部达到 100%；
• Load Average 长期维持在 4 左右；
• 多个进程以 postgres 用户运行；
• 进程名称为随机字符串 dzZ7yVrxv7；
• 单个进程的 CPU 使用率超过 200%；
• 进程占用了大量内存。

进一步执行：

sudo ps -eo user,pid,ppid,lstart,etime,%cpu,%mem,stat,comm,args \
  --sort=-%cpu | head -20

其中一个主要进程如下：

USER       PID   PPID  %CPU  %MEM  STAT  COMMAND
postgres   9918     1   377  29.8  Ssl   dzZ7yVrxv7

这不是正常的 PostgreSQL 进程。

正常情况下，PostgreSQL 进程名称通常类似：

postgres
postgres: checkpointer
postgres: background writer
postgres: walwriter
postgres: autovacuum launcher

而本次进程具有以下异常特征：

• 名称为随机字符串；
• 以 postgres 用户运行；
• CPU 使用率接近 4 个核心；
• 父进程已经变成 PID 1；
• 内存占用异常高。

因此，初步判断这不是正常数据库负载，而是疑似挖矿程序或其他恶意程序。

分析问题：确认恶意程序来源

1. 检查进程真实文件

Linux 进程名称可以被修改或伪装，所以不能只看 COMMAND，需要检查 /proc/<PID>/exe。

执行：

sudo sh -c '
echo "EXE:"
ls -l /proc/9918/exe

echo "CWD:"
ls -l /proc/9918/cwd

echo "CMDLINE:"
tr "\0" " " < /proc/9918/cmdline
echo

echo "CGROUP:"
cat /proc/9918/cgroup
'

输出如下：

EXE:
/proc/9918/exe -> /dev/shm/gJppJl6TbG (deleted)

CWD:
/proc/9918/cwd -> /var/lib/postgresql

CMDLINE:
dzZ7yVrxv7

CGROUP:
0::/system.slice/cron.service

这几项信息非常关键。

可执行文件位于 /dev/shm

真实程序路径为：

/dev/shm/gJppJl6TbG

/dev/shm 是基于内存的临时文件系统。恶意程序经常将文件下载到这里，再从内存文件系统中执行，以减少在磁盘上的痕迹。

原文件已经被删除

路径末尾显示：

(deleted)

说明程序启动后，磁盘上的原文件已被删除。但由于进程仍然持有该文件，程序依然可以继续运行。

这种“启动后删除自身”的行为是常见的恶意程序隐藏手段。

工作目录属于 PostgreSQL 用户

进程工作目录是：

/var/lib/postgresql

这说明恶意程序与 postgres 用户的主目录有关。

进程由 cron 启动

cgroup 显示：

/system.slice/cron.service

这说明程序是通过定时任务启动的。

2. 从运行中的进程保存样本

因为原始文件已经被删除，如果立即结束进程，可能无法再提取样本。因此先从 /proc 保存程序：

sudo mkdir -p /root/incident
sudo chmod 700 /root/incident

sudo cp -L /proc/9918/exe \
  /root/incident/suspect-9918.bin

sudo chmod 600 \
  /root/incident/suspect-9918.bin

检查文件类型：

sudo file /root/incident/suspect-9918.bin

结果如下：

ELF 64-bit LSB shared object, x86-64,
statically linked, no section header

计算 SHA-256：

sudo sha256sum /root/incident/suspect-9918.bin

得到：

d32f9eef63c496a146a6a811677dd27e337db993d6f1a4b1af145c3135d391b3

该文件具有以下特征：

• 随机文件名；
• 位于 /dev/shm；
• 静态链接；
• 没有节区表；
• 启动后删除原文件；
• 持续占用全部 CPU。

这些行为进一步证明它不是正常的 PostgreSQL 组件。

3. 检查 PostgreSQL 用户的定时任务

由于进程是从 cron.service 启动的，继续检查 postgres 用户的 crontab：

sudo crontab -u postgres -l

发现如下任务：

24 * * * * /var/lib/postgresql/.dbus-XGodM5jOyL

该任务会在每小时第 24 分钟执行一次隐藏脚本：

/var/lib/postgresql/.dbus-XGodM5jOyL

文件名使用了以点开头的隐藏形式，并模仿了 D-Bus 的命名方式，很容易被误认为系统文件。

检查 cron 日志：

sudo journalctl -u cron.service \
  --since "2026-08-15 07:15:00" \
  --until "2026-08-15 09:15:00" \
  --no-pager

日志中可以看到：

Aug 15 07:24:01 CRON: (postgres) CMD (/var/lib/postgresql/.dbus-XGodM5jOyL)
Aug 15 08:24:01 CRON: (postgres) CMD (/var/lib/postgresql/.dbus-XGodM5jOyL)

这证明恶意脚本至少在 07:24 和 08:24 被执行过。

4. 分析恶意启动脚本

检查文件：

sudo file /var/lib/postgresql/.dbus-XGodM5jOyL
sudo stat /var/lib/postgresql/.dbus-XGodM5jOyL
sudo sha256sum /var/lib/postgresql/.dbus-XGodM5jOyL

结果显示它是一个 Bash 脚本：

Bourne-Again shell script, ASCII text executable,
with very long lines

对应 SHA-256：

36b1dcf43876f55aae2b8be7dada848b41f60ec61cd4ca7ab2a1278193f286f0

这份脚本负责下载、启动或恢复恶意程序，也是恶意进程能够周期性出现的主要持久化机制。

如果只结束高 CPU 进程，而不清理这条 cron，恶意程序会在下一个小时的第 24 分钟再次出现。

5. 在用户目录中发现第二个恶意下载器

停止并卸载 PostgreSQL 后，我继续检查 /var/lib/postgresql 的残留文件：

sudo find /var/lib/postgresql \
  -xdev -maxdepth 10 -ls

发现了另一个可疑文件：

/var/lib/postgresql/.config/systemd/user/
└── systemd-tmpfiles-cleanup/
    └── systemd-tmpfiles-cleanup-TNWow7.sh

这个文件使用了：

systemd-tmpfiles-cleanup

作为目录名，试图伪装成正常的 systemd 临时文件清理组件。

检查文件类型和哈希：

sudo file \
  /var/lib/postgresql/.config/systemd/user/systemd-tmpfiles-cleanup/systemd-tmpfiles-cleanup-TNWow7.sh

sudo sha256sum \
  /var/lib/postgresql/.config/systemd/user/systemd-tmpfiles-cleanup/systemd-tmpfiles-cleanup-TNWow7.sh

结果为：

Bourne-Again shell script, ASCII text executable,
with very long lines

SHA-256：

9962de5e0c68ea6e85879c5f62f2d0806360dbe186dc15e1d59abf8e4209de11

脚本内容经过 Base64 编码，末尾直接执行：

base64 -d | bash

解码后的逻辑显示，它具备以下行为：

• 通过 Tor、SOCKS5 或 Tor2web 连接外部地址；
• 获取服务器公网 IP；
• 收集当前用户名、主机名和内核版本；
• 读取机器 ID；
• 从外部下载其他程序；
• 在 /dev/shm、/tmp、/var/tmp 等目录测试和执行文件；
• 启动程序后删除临时文件。

这已经不只是一个单纯的高 CPU 进程，而是一套包含下载、执行、隐藏和持久化能力的恶意程序。

为什么 PostgreSQL 没有开放公网端口，仍然存在风险？

Azure 网络安全组当时只允许公网访问：

• TCP 22；
• TCP 80；
• TCP 443。

并没有允许公网直接访问 PostgreSQL 的 5432 端口。

但检查服务器本机监听状态时发现：

sudo ss -lntp | grep ':5432'

输出为：

LISTEN 0 244 0.0.0.0:5432 0.0.0.0:*
LISTEN 0 244 [::]:5432    [::]:*

这说明 PostgreSQL 在操作系统层面监听了所有 IPv4 和 IPv6 网卡。

虽然 Azure NSG 没有向公网放行 5432，但以下风险依然存在。

1. 同一虚拟网络中的主机仍可能访问

Azure NSG 默认存在 AllowVnetInBound 规则，同一虚拟网络中的其他服务器可能访问该端口。

如果同一 VNet 内的其他服务器被入侵，攻击者就可能通过内网继续攻击数据库服务器。

2. 本机应用或容器仍可能访问

即使公网无法连接，服务器本机运行的以下组件仍然可能访问 PostgreSQL：

• Web 应用；
• Docker 容器；
• CI/CD Agent；
• 其他被攻陷的服务；
• 本机恶意程序。

网络安全组无法阻止服务器本机进程访问本机数据库。

3. 风险不只来自数据库端口

本次恶意程序的实际持久化位置是：

• postgres 用户的 crontab；
• /var/lib/postgresql 用户目录；
• 用户级 systemd 配置目录；
• /dev/shm 临时执行目录。

即使 PostgreSQL 服务停止，只要这些用户、目录和定时任务仍然存在，恶意程序就可能继续运行。

所以，数据库的安全边界不只是 5432 端口，还包括：

• 操作系统账户；
• 数据目录；
• 用户主目录；
• cron；
• systemd；
• SSH；
• 软件包；
• 配置文件；
• 历史镜像和备份。

4. 未使用的软件往往更容易被忽略

这台服务器的业务实际使用 MySQL，PostgreSQL 并没有业务用途。

由于“不使用”，它反而容易长期处于以下状态：

• 没有人检查配置；
• 没有人检查系统用户；
• 没有人检查数据库日志；
• 没有人检查用户的 cron；
• 没有人检查相关目录；
• 没有人确认是否仍然需要；
• 没有人关注其补丁和版本。

因此：

未使用但仍然安装和运行的软件，并不是备用能力，而是未被管理的攻击面。

解决问题：清除恶意程序并卸载 PostgreSQL

1. 暂停恶意进程

取证完成后，先暂停进程：

sudo kill -STOP 9918

检查进程状态：

ps -p 9918 \
  -o user,pid,ppid,%cpu,%mem,stat,comm,args

状态中出现 T，说明进程已暂停。

暂停的好处是：

• 立即停止继续占用 CPU；
• 暂时停止潜在网络行为；
• 保留进程，便于继续调查；
• 避免在完成取证前丢失内存中的样本。

2. 备份并删除恶意 cron

先保存 crontab：

sudo crontab -u postgres -l \
  > /root/incident/postgres-crontab.txt

然后删除：

sudo crontab -u postgres -r

确认已删除：

sudo crontab -u postgres -l

预期输出：

no crontab for postgres

3. 隔离恶意启动脚本

先备份脚本：

sudo cp -a \
  /var/lib/postgresql/.dbus-XGodM5jOyL \
  /root/incident/cron-payload

再从原位置移走：

sudo mv \
  /var/lib/postgresql/.dbus-XGodM5jOyL \
  /root/incident/original-dbus-XGodM5jOyL

限制证据文件权限：

sudo chown root:root \
  /root/incident/original-dbus-XGodM5jOyL \
  /root/incident/cron-payload

sudo chmod 600 \
  /root/incident/original-dbus-XGodM5jOyL \
  /root/incident/cron-payload

4. 结束恶意进程

确认恶意 cron 和启动脚本已隔离后，结束进程：

sudo kill -KILL 9918

检查进程是否消失：

ps -p 9918 \
  -o user,pid,ppid,%cpu,%mem,stat,comm,args

随后查看系统负载：

uptime

清理后的负载变为：

load average: 0.36, 2.71, 3.68

1 分钟负载已经从 4 以上下降到 0.36。

5 分钟和 15 分钟负载仍然较高是正常的，因为它们反映的是一段时间内的平均值，会逐渐下降。

5. 停止并禁用 PostgreSQL

因为业务并不使用 PostgreSQL，所以先停止并禁止开机启动：

sudo systemctl disable --now postgresql

确认服务状态：

systemctl status postgresql --no-pager

确认端口不再监听：

sudo ss -lntp | grep ':5432' \
  || echo "5432 端口未监听"

最终结果为：

5432 端口未监听

6. 卸载 PostgreSQL

确认业务没有受到影响后，卸载 PostgreSQL 相关软件包：

sudo apt-get purge -y \
  postgresql \
  postgresql-14 \
  postgresql-client-14 \
  postgresql-client-common \
  postgresql-common \
  postgresql-contrib

需要注意：

卸载软件包不等于完成恶意程序清理。

还应继续检查以下位置：

/var/lib/postgresql
/etc/postgresql
/etc/postgresql-common
/var/spool/cron
/tmp
/var/tmp
/dev/shm
/home/*/.config/systemd

本次发现的第二个恶意下载器，就是在卸载 PostgreSQL 后检查残留目录时找到的。

7. 隔离第二个恶意下载器

将伪装成 systemd 清理任务的脚本移入证据目录：

sudo mv \
  /var/lib/postgresql/.config/systemd/user/systemd-tmpfiles-cleanup/systemd-tmpfiles-cleanup-TNWow7.sh \
  /root/incident/systemd-tmpfiles-cleanup-TNWow7.sh

限制权限：

sudo chown root:root \
  /root/incident/systemd-tmpfiles-cleanup-TNWow7.sh

sudo chmod 600 \
  /root/incident/systemd-tmpfiles-cleanup-TNWow7.sh

然后搜索是否存在同类文件：

sudo grep -RIlE \
  'TNWow7|XGodM5jOyL|tor2socks|tor2web|relay\.tor2socks' \
  /etc \
  /var/spool/cron \
  /var/lib/postgresql \
  /tmp \
  /var/tmp \
  /dev/shm \
  /home \
  2>/dev/null

Azure 网络安全配置整改

1. 不需要删除不存在的 5432 入站规则

Azure NSG 中原本没有允许公网访问 5432 的规则，所以不需要专门删除 PostgreSQL 入站规则。

停止并卸载 PostgreSQL 后，本机也已经不再监听 5432。

但是，不能因为 NSG 没有开放 5432 就认为服务器已经安全。

2. 收紧 SSH 入站范围

排查过程中，SSH 日志中出现了多个公网 IP 对 postgres 用户进行密码尝试：

Failed password for postgres from 172.83.83.194
Failed password for postgres from 101.36.110.41

这些记录显示的是失败登录，不能说明对方已经通过 SSH 登录成功。但它们说明服务器的 SSH 正在被公网持续扫描。

原 Azure SSH 规则为：

Source: Any
Destination port: 22
Action: Allow

建议改为：

Source: 管理员固定公网 IP/32
Destination port: 22
Protocol: TCP
Action: Allow

更安全的方式包括：

• Azure Bastion；
• VPN；
• Just-In-Time VM Access；
• 禁止 SSH 密码登录；
• 只使用 SSH Key；
• 禁止 root 远程登录；
• 配置失败登录告警。

3. 限制服务器出站访问

恶意脚本需要连接外部地址下载程序，而当时 Azure NSG 允许任意出站访问。

如果业务条件允许，应限制服务器的出站范围：

• 只允许必要的 DNS；
• 只允许必要的软件源；
• 只允许业务需要访问的 API；
• 使用 Azure Firewall 或集中式代理；
• 记录 DNS 和出站网络日志；
• 对 Tor、代理、矿池和异常域名建立告警。

仅限制入站流量是不够的。恶意程序一旦进入服务器，通常还需要通过出站网络下载载荷、连接控制服务器或矿池。

为什么建议使用 Azure 托管 PostgreSQL？

如果业务确实需要 PostgreSQL，建议优先使用：

Azure Database for PostgreSQL

而不是直接在 Azure VM 上安装 PostgreSQL。

1. 减少操作系统层面的攻击面

在 VM 上自建 PostgreSQL，需要自行维护：

• Linux 操作系统；
• PostgreSQL 软件包；
• postgres 系统用户；
• SSH；
• cron；
• systemd；
• 数据目录权限；
• 安全补丁；
• 版本升级；
• 网络防火墙；
• 日志；
• 备份；
• 高可用；
• 恶意进程检测。

使用 Azure 托管 PostgreSQL 后，用户不会直接管理数据库所在主机的 root 权限，也不会在数据库主机上创建 cron、systemd 服务或运行 /dev/shm 中的程序。

这可以显著减少本次事件中出现的主机级风险。

2. 使用私有网络，关闭公网访问

建议采用以下网络架构：

Azure VM / App Service / AKS
          |
      Private Network
          |
Azure Database for PostgreSQL

数据库应配置为：

• 禁止公共网络访问；
• 使用 Private Endpoint 或私有网络集成；
• 只允许应用所在子网访问；
• 不向公网开放数据库端口；
• 数据库管理也通过 VPN、Bastion 或受控网络完成。

3. 自动备份和维护

Azure 托管 PostgreSQL 可以提供：

• 自动备份；
• 时间点恢复；
• 高可用选项；
• 数据加密；
• 监控指标；
• 日志与告警；
• 平台维护；
• 安全更新；
• 版本支持。

这些能力可以降低因长期无人维护而产生的风险。

4. 责任边界更清晰

自建 PostgreSQL 经常出现这种情况：

为了测试临时安装，后来业务不用了，但服务、用户和目录一直留在服务器上。

托管数据库的资源边界更加清晰：

• 需要时创建；
• 通过私有网络连接；
• 不再使用时导出数据；
• 删除数据库实例；
• 删除访问权限和私有连接；
• 不会在业务 VM 上留下数据库系统用户和历史脚本。

5. 托管服务并不等于绝对安全

Azure 托管 PostgreSQL 可以减少操作系统和基础设施维护风险，但仍需要正确管理：

• 数据库账号；
• 强密码或身份认证；
• 最小权限；
• 网络访问范围；
• SQL 注入；
• 连接字符串；
• Azure Key Vault；
• 日志审计；
• 数据加密；
• 应用依赖；
• 凭据轮换。

正确的理解是：

Azure 托管 PostgreSQL 缩小了需要自己负责的安全范围，但不会消除应用和账号层面的安全责任。

本次事件的 IOC

以下指标可用于内部服务器排查。

可疑进程及文件名

dzZ7yVrxv7
gJppJl6TbG
.dbus-XGodM5jOyL
systemd-tmpfiles-cleanup-TNWow7.sh

SHA-256

恶意 ELF 程序：

d32f9eef63c496a146a6a811677dd27e337db993d6f1a4b1af145c3135d391b3

恶意 cron 启动脚本：

36b1dcf43876f55aae2b8be7dada848b41f60ec61cd4ca7ab2a1278193f286f0

恶意下载器：

9962de5e0c68ea6e85879c5f62f2d0806360dbe186dc15e1d59abf8e4209de11

行为特征

• 以 postgres 用户运行；
• 从 /dev/shm 执行随机名称文件；
• 启动后删除原文件；
• 利用用户 crontab 定时启动；
• Base64 解码后直接交给 Bash 执行；
• 使用 Tor、SOCKS5 或 Tor2web；
• 收集公网 IP、用户名、主机名和机器 ID；
• 从外部下载其他程序；
• 在 /tmp、/var/tmp 和 /dev/shm 中执行程序；
• 持续占用全部 CPU；
• 伪装成 D-Bus 或 systemd 组件。

最终总结

本次事件从表面上看，是一次服务器 CPU 占用过高的问题。

但深入排查后发现，真正的问题包括：

• 以 postgres 用户运行的恶意程序；
• 位于 /dev/shm 的随机 ELF 文件；
• postgres 用户的恶意 cron；
• /var/lib/postgresql 下的隐藏启动脚本；
• 伪装成 systemd 组件的恶意下载器；
• 可连接 Tor 和外部下载地址的恶意逻辑。

最值得关注的是：

这台服务器没有通过 Azure NSG 向公网开放 PostgreSQL 的 5432 端口，而且业务也没有使用 PostgreSQL，但与 PostgreSQL 有关的系统用户、主目录、cron 和残留文件仍然构成了安全风险。

当然，现有证据并不能证明初始入侵入口就是 PostgreSQL。恶意程序使用 postgres 用户运行，不等于攻击者一定通过 PostgreSQL 端口进入服务器。

但这次事件依然说明了几个重要原则。

第一，不使用的服务应立即停止和卸载

不要因为“没有向公网开放”就长期保留闲置服务。

不使用的软件应当：

• 停止服务；
• 禁止开机启动；
• 卸载软件包；
• 检查系统用户；
• 检查 cron；
• 检查 systemd；
• 检查残留目录和脚本。

第二，云安全组不是唯一安全边界

NSG 没有开放 5432，只能说明公网无法通过该规则直接连接数据库，不能防止：

• 内网访问；
• 本机访问；
• 容器访问；
• 历史持久化；
• 用户级 cron；
• 本机恶意程序；
• SSH 和应用漏洞。

第三，生产 PostgreSQL 优先使用 Azure 托管服务

如果没有必须自建数据库服务器的明确需求，建议使用：

Azure Database for PostgreSQL + 私有网络 + 禁止公共访问。

这样可以减少数据库主机操作系统、SSH、系统用户、cron、systemd、补丁、备份和高可用等方面的维护风险。

第四，杀掉恶意进程不等于完成安全恢复

结束高 CPU 进程只解决了当前资源占用问题，还应继续：

• 查找持久化；
• 调查入侵入口；
• 检查 SSH 成功登录记录；
• 检查 Web 应用和容器；
• 轮换服务器上的全部凭据；
• 检查同一 VNet 中的其他主机；
• 保存日志和磁盘快照；
• 必要时从可信镜像重建服务器。

最终可以将这次事件概括为一句话：

不使用的数据库不要留在服务器上；需要 PostgreSQL 时，优先使用 Azure 托管 PostgreSQL，并通过私有网络访问。

随着 OpenWebUI 中的用户、对话、文件和知识库数据不断增长，原先部署在 Azure VM 上的自建 PostgreSQL 带来了越来越多的运维工作，包括数据库补丁、备份、故障恢复、存储监控和安全维护。

为了降低维护成本并提高数据库可靠性，我将 OpenWebUI 的业务数据库从 VM 本地 PostgreSQL 迁移到了 Azure Database for PostgreSQL Flexible Server。

这次迁移采用了：

在线全量迁移 + 数据一致性验证 + 活跃对话增量同步 + 快速切换

全量数据库导出和恢复期间，OpenWebUI 始终保持在线。最终切换仅涉及一次很短的 Docker 容器重建，用户侧基本无感。

本文中的服务器地址、数据库名称、用户名、密码和资源标识均已隐藏或替换为占位符。

迁移背景

OpenWebUI 以 Docker 容器形式运行在 Azure VM 中，最初使用安装在同一台 VM 上的 PostgreSQL。

迁移前的架构如下：

用户
  │
  ▼
Azure VM
  ├── OpenWebUI Docker 容器
  │      └── 连接 VM 宿主机 PostgreSQL
  │
  └── PostgreSQL
         └── 数据保存在 VM 本地磁盘

这种部署方式比较简单，但随着应用逐渐稳定运行，数据库维护也成为了新的负担。

需要自行处理的工作包括：

• PostgreSQL 安全更新和补丁
• 数据库备份及备份轮换
• 数据恢复和恢复演练
• 磁盘容量监控
• 数据库服务监控
• PostgreSQL 版本升级
• 故障处理
• 网络和访问权限管理

对于 OpenWebUI 这样的应用来说，数据库是重要的状态组件，但并不是应用的核心运维目标。因此，将 PostgreSQL 迁移到 Azure 托管服务是一个更合理的选择。

迁移后的架构

迁移后的架构如下：

用户
  │
  ▼
Azure VM
  └── OpenWebUI Docker 容器
          │
          ├── Private Endpoint
          │       └── Azure Database for PostgreSQL
          │
          └── 宿主机持久化目录
                  ├── uploads
                  ├── vector_db
                  └── cache

最终实现了：

• OpenWebUI 使用 Azure 托管 PostgreSQL
• 数据库通过 Private Endpoint 私网访问
• 数据库连接启用 TLS
• PostgreSQL 不再占用 VM 本地端口和磁盘
• OpenWebUI 上传文件和向量数据实现持久化挂载
• Azure 自动执行数据库备份
• VM 上只保留 PostgreSQL 客户端，用于日常管理 Azure 数据库

为什么选择 Azure Database for PostgreSQL

1. 降低数据库运维成本

Azure Database for PostgreSQL Flexible Server 是一项托管数据库服务。

与 VM 自建 PostgreSQL 相比，Azure 可以帮助处理大量底层工作，例如：

• 数据库基础设施维护
• 自动备份
• 事务日志备份
• 时间点恢复
• 监控指标采集
• 存储管理
• 计划性维护
• 可选高可用
• 可选只读副本

迁移完成后，VM 只需要负责运行 OpenWebUI，数据库生命周期则交给 Azure 管理。

2. 自动备份和时间点恢复

Azure PostgreSQL 提供内置自动备份，并持续备份事务日志，支持时间点恢复（Point-in-Time Restore，PITR）。

当前环境配置了自动备份保留策略。发生误操作时，可以在保留期内创建一台恢复到指定时间点的新服务器。

与自行编写 pg_dump 和 Cron 脚本相比，Azure 托管备份具有以下优势：

• 不需要维护备份脚本
• 不需要手动轮换备份文件
• 不会占用 VM 本地磁盘
• 可以恢复到保留期内的特定时间
• 备份操作由平台统一管理

需要注意的是，Azure 内置备份主要用于平台恢复，不等同于可随意下载的逻辑备份文件。

如果有以下需求，仍建议额外定期执行 pg_dump：

• 长期离线归档
• 跨平台恢复
• 数据审计
• 跨订阅或跨云迁移
• 保留期超过平台备份策略

3. 使用 Private Endpoint 私网访问

本次迁移没有将 PostgreSQL 直接暴露到公网，而是为 Azure PostgreSQL 配置了 Private Endpoint。

OpenWebUI 访问数据库时，数据库域名通过 Private DNS 解析到 VNet 中的私有 IP：

Azure PostgreSQL FQDN
        ↓
Private DNS
        ↓
Private Endpoint 私有 IP

从 OpenWebUI 容器内部进行了两层验证：

1. DNS 是否解析到私有地址
2. TCP 5432 是否可以通过私网访问

示例：

docker exec -i open-webui python3 - <<'PY'
import socket

host = "<AZURE_POSTGRESQL_PRIVATE_FQDN>"
port = 5432

addresses = sorted({
    item[4][0]
    for item in socket.getaddrinfo(
        host,
        port,
        type=socket.SOCK_STREAM
    )
})

print("Resolved addresses:", addresses)

with socket.create_connection((host, port), timeout=5) as sock:
    print("TCP connection: OK")
    print("Connected peer:", sock.getpeername())
PY

数据库安全性并不只是来自 Private Endpoint，而是来自以下措施的组合：

• Private Endpoint
• Private DNS
• VNet 隔离
• NSG 和路由控制
• 禁用或限制公网访问
• PostgreSQL 身份认证
• TLS 链路加密
• 最小权限数据库账号

4. 数据库连接启用 TLS

OpenWebUI 的数据库连接串启用了：

sslmode=require

脱敏后的连接串格式如下：

postgresql://<APP_USER>:<PASSWORD>@<AZURE_POSTGRESQL_FQDN>:5432/<APP_DATABASE>?sslmode=require

迁移前还通过 OpenWebUI 使用的 Python 和 SQLAlchemy 环境实际验证了 TLS：

import os
from sqlalchemy import create_engine, text

engine = create_engine(os.environ["DATABASE_URL"])

with engine.connect() as conn:
    ssl_enabled = conn.execute(text("""
        SELECT ssl
        FROM pg_stat_ssl
        WHERE pid = pg_backend_pid()
    """)).scalar_one()

print("TLS enabled:", ssl_enabled)

如果安全要求更高，可以进一步使用：

sslmode=verify-full

这种模式不仅加密连接，还会验证证书和服务器主机名，但需要正确配置 CA 证书，并使用与证书匹配的服务器 FQDN。

5. 更容易扩展可靠性能力

迁移到 Azure PostgreSQL 后，可以根据 OpenWebUI 的使用规模继续配置：

• 计算规格扩缩容
• 存储扩容
• 可用区高可用
• 只读副本
• 慢查询分析
• 数据库连接监控
• CPU、内存和存储告警
• 更长的备份保留期
• 异地恢复策略

这使 OpenWebUI 的数据库层从“单 VM 上的本地服务”升级为独立、可管理的托管数据服务。

迁移目标：让 OpenWebUI 尽量保持在线

传统迁移通常采用以下流程：

停止应用
  ↓
导出数据库
  ↓
恢复目标数据库
  ↓
修改连接配置
  ↓
重新启动应用

这种方式虽然简单，但数据库越大，停机时间越长。

本次迁移采用了不同策略：

在线全量备份
  ↓
在线恢复到 Azure PostgreSQL
  ↓
验证结构、权限和数据
  ↓
同步迁移期间新增的活跃对话
  ↓
快速重建 OpenWebUI 容器

在以下阶段，OpenWebUI 都保持在线：

• 全量 pg_dump
• Azure PostgreSQL 数据恢复
• 表结构验证
• 数据量对比
• Private Endpoint 验证
• TLS 验证
• 增量数据同步

最终只有更换 DATABASE_URL 并重建容器时发生了短暂连接中断。

因此，更准确地说，这是一种：

近零停机、用户侧近乎无感知的 OpenWebUI 数据库迁移方案。

迁移前检查 OpenWebUI

1. 确认 OpenWebUI 使用的数据库类型

首先检查 OpenWebUI 容器环境变量：

docker inspect open-webui \
  --format '{{range .Config.Env}}{{println .}}{{end}}' |
grep -E 'DATABASE_URL|DATA_DIR|WEBUI_SECRET_KEY'

确认 OpenWebUI 已经使用 PostgreSQL，而不是默认 SQLite：

DATABASE_URL=postgresql://<LOCAL_USER>:***@<LOCAL_HOST>:5432/<LOCAL_DATABASE>

由于源端和目标端都是 PostgreSQL，因此可以直接使用：

pg_dump → pg_restore

不需要使用 SQLite 到 PostgreSQL 的转换工具。

2. 检查源数据库

检查 PostgreSQL 版本和数据库大小：

sudo -u postgres psql \
  -d <LOCAL_DATABASE> \
  -c "
SELECT
  current_database(),
  current_setting('server_version'),
  pg_size_pretty(
    pg_database_size(current_database())
  );
"

同时检查源数据库使用了哪些扩展：

sudo -u postgres psql \
  -d <LOCAL_DATABASE> \
  -c "
SELECT extname, extversion
FROM pg_extension
ORDER BY extname;
"

本次源数据库没有使用额外的第三方扩展，因此降低了跨环境迁移的兼容性风险。

3. 检查 OpenWebUI 的本地文件

数据库并不是 OpenWebUI 的全部数据。

检查容器挂载后发现，原容器没有配置持久化 volume，而 /app/backend/data 中已经存在大量数据：

/app/backend/data
├── cache
├── uploads
└── vector_db

这些内容包括：

• 用户上传文件
• 向量数据库
• 缓存
• 其他应用本地状态

它们不会进入 PostgreSQL 的 pg_dump，因此必须单独处理。

这也是本次迁移中一个非常重要的发现：

迁移 OpenWebUI 的 PostgreSQL，并不等于迁移了 OpenWebUI 的全部数据。

准备 Azure PostgreSQL

1. 创建独立应用账号

不建议让 OpenWebUI 长期使用 Azure PostgreSQL 管理员账号。

在目标服务器中创建专用角色：

CREATE ROLE <APP_USER> LOGIN;

通过 psql 交互方式设置密码，可以避免密码出现在 Shell 历史记录中：

\password <APP_USER>

然后创建目标数据库：

CREATE DATABASE <APP_DATABASE>
OWNER <APP_USER>;

2. 验证应用账号

psql \
  "host=<AZURE_POSTGRESQL_FQDN> \
   port=5432 \
   dbname=<APP_DATABASE> \
   user=<APP_USER> \
   sslmode=require" \
  -W \
  -c "SELECT current_user, current_database();"

同时确认目标数据库为空：

SELECT count(*)
FROM information_schema.tables
WHERE table_schema = 'public'
  AND table_type = 'BASE TABLE';

3. 处理 public schema 权限

第一次测试恢复时遇到了：

ERROR: permission denied for schema public

原因是应用账号虽然可以连接数据库，但没有在 public schema 中创建对象的权限。

使用管理员账号连接目标数据库后执行：

ALTER SCHEMA public OWNER TO <APP_USER>;

GRANT USAGE, CREATE
ON SCHEMA public
TO <APP_USER>;

这个问题说明，仅验证账号“能否登录”还不够，还需要确认该账号能否：

• 创建表
• 创建索引
• 创建序列
• 创建约束
• 执行 OpenWebUI 的 Alembic 数据库迁移

在线执行全量数据库迁移

1. 在线导出 OpenWebUI 数据库

PostgreSQL 的 pg_dump 会基于一致性事务快照导出数据，因此可以在 OpenWebUI 继续运行时执行。

sudo -u postgres pg_dump \
  --dbname=<LOCAL_DATABASE> \
  --format=custom \
  --no-owner \
  --no-acl \
  --file=/tmp/openwebui-pre-migration.dump

参数含义：

• --format=custom：使用 PostgreSQL 自定义归档格式
• --no-owner：不恢复源端对象 owner
• --no-acl：不恢复源端权限
• --file：指定备份文件

检查归档是否有效：

pg_restore \
  --list \
  /tmp/openwebui-pre-migration.dump |
head -30

自定义格式会保留：

• 表结构
• 表数据
• 主键
• 唯一约束
• 索引
• 外键
• 序列
• Alembic 迁移版本

2. 恢复到 Azure PostgreSQL

pg_restore \
  --host=<AZURE_POSTGRESQL_FQDN> \
  --port=5432 \
  --username=<APP_USER> \
  --dbname=<APP_DATABASE> \
  --no-owner \
  --no-acl \
  --exit-on-error \
  --verbose \
  /tmp/openwebui-pre-migration.dump

使用：

--exit-on-error

可以确保遇到恢复错误时立即停止，避免忽略关键问题。

恢复成功后更新统计信息：

psql \
  "host=<AZURE_POSTGRESQL_FQDN> \
   port=5432 \
   dbname=<APP_DATABASE> \
   user=<APP_USER> \
   sslmode=require" \
  -W \
  -c "ANALYZE;"

对比源端与目标端数据

恢复完成后，需要对 OpenWebUI 的核心表进行对比。

示例查询：

SELECT
  (SELECT count(*) FROM "user") AS users,
  (SELECT count(*) FROM chat) AS chats,
  (SELECT count(*) FROM chat_message) AS chat_messages,
  (SELECT count(*) FROM file) AS files,
  (SELECT count(*) FROM knowledge) AS knowledge,
  (
    SELECT count(*)
    FROM information_schema.tables
    WHERE table_schema = 'public'
      AND table_type = 'BASE TABLE'
  ) AS tables;

重点检查：

• 用户数量
• 对话数量
• 消息数量
• 文件记录数量
• 知识库数量
• 业务表数量
• Alembic 版本
• 表 owner
• 序列状态

对比时发现，目标端的对话消息比源端少了少量记录。

这并不是恢复失败，而是因为：

在全量备份和恢复过程中，OpenWebUI 仍然在线，当前迁移操作的对话还在不断产生新消息。

因此，下一步需要同步全量快照之后新增的数据。

同步迁移期间新增的活跃对话

本次迁移期间，主要只有当前操作对话仍在更新，因此没有再次恢复整个数据库，而是只同步当前活跃对话。

涉及两张表：

chat
chat_message

1. 找到最近更新的对话

SELECT
  c.id,
  c.title,
  to_timestamp(c.updated_at) AS updated_at,
  count(cm.id) AS message_count
FROM chat c
LEFT JOIN chat_message cm
  ON cm.chat_id = c.id
GROUP BY
  c.id,
  c.title,
  c.updated_at
ORDER BY c.updated_at DESC
LIMIT 5;

确定活跃对话后，后续脚本通过环境变量或参数接收对话 ID，而不是将其直接写入公开文档：

CHAT_ID="<ACTIVE_CHAT_ID>"

2. 使用一致性快照导出对话数据

为了保证 chat 和 chat_message 来自同一个时间点，使用只读、可重复读事务：

BEGIN TRANSACTION
ISOLATION LEVEL REPEATABLE READ
READ ONLY;

然后在同一事务中导出：

\copy (
  SELECT *
  FROM chat
  WHERE id = '<ACTIVE_CHAT_ID>'
) TO '/tmp/chat.csv'
WITH (FORMAT CSV);

\copy (
  SELECT *
  FROM chat_message
  WHERE chat_id = '<ACTIVE_CHAT_ID>'
  ORDER BY created_at, id
) TO '/tmp/chat-messages.csv'
WITH (FORMAT CSV);

最后提交：

COMMIT;

需要注意：psql 的 \copy 是客户端元命令，复杂字段列表最好写在同一行，否则可能出现：

\copy: parse error at end of line

3. 在 Azure 中使用临时表和 UPSERT

目标端创建临时 staging 表：

CREATE TEMP TABLE stage_chat
(LIKE public.chat INCLUDING DEFAULTS);

CREATE TEMP TABLE stage_chat_message
(LIKE public.chat_message INCLUDING DEFAULTS);

将 CSV 导入临时表后，对 chat 主记录执行 UPSERT：

INSERT INTO public.chat (...)
SELECT ...
FROM stage_chat
ON CONFLICT (id) DO UPDATE SET
  title              = EXCLUDED.title,
  updated_at         = EXCLUDED.updated_at,
  chat               = EXCLUDED.chat,
  meta               = EXCLUDED.meta,
  current_message_id = EXCLUDED.current_message_id;

对消息表执行类似操作：

INSERT INTO public.chat_message (...)
SELECT ...
FROM stage_chat_message
ON CONFLICT (id) DO UPDATE SET
  content         = EXCLUDED.content,
  output          = EXCLUDED.output,
  status_history  = EXCLUDED.status_history,
  error           = EXCLUDED.error,
  usage           = EXCLUDED.usage,
  done            = EXCLUDED.done,
  updated_at      = EXCLUDED.updated_at,
  context_summary = EXCLUDED.context_summary;

为了让 Azure 中该对话的消息集合与源快照完全一致，还会删除目标端多余记录：

DELETE FROM public.chat_message target
WHERE target.chat_id = '<ACTIVE_CHAT_ID>'
  AND NOT EXISTS (
    SELECT 1
    FROM stage_chat_message staged
    WHERE staged.id = target.id
  );

整个导入和 UPSERT 过程放在一个事务中执行：

BEGIN;

-- 创建临时表
-- 导入数据
-- UPSERT
-- 清理多余记录

COMMIT;

如果任何步骤失败，事务会自动回滚，不会留下部分同步数据。

最终快速切换 OpenWebUI

完成在线全量迁移后，最终操作为：

最后同步一次当前活跃对话
              ↓
重建 OpenWebUI 容器
              ↓
新容器连接 Azure PostgreSQL

示例：

./sync-active-chat-to-azure.sh && \
docker compose \
  -f run-with-azure-pg.yml \
  up -d --force-recreate

完整数据库已经提前迁移并验证，因此最终阶段不需要再次等待几百 MB 数据恢复，只需要同步少量增量记录并快速重建容器。

这将切换窗口缩短到了容器启动所需的时间。

安全保存 OpenWebUI 数据库连接串

数据库连接串没有直接写入 Compose 文件，而是放在独立环境文件中：

open-webui-azure-db.env

文件内容形式：

DATABASE_URL=postgresql://<APP_USER>:<URL_ENCODED_PASSWORD>@<AZURE_POSTGRESQL_FQDN>:5432/<APP_DATABASE>?sslmode=require

文件权限设置为：

chmod 600 open-webui-azure-db.env

如果密码包含特殊字符，需要先进行 URL 编码：

python3 - <<'PY'
import getpass
import urllib.parse

password = getpass.getpass("Database password: ")
print(urllib.parse.quote(password, safe=""))
PY

新的 Compose 文件示例：

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:<VERSION>
    container_name: open-webui
    restart: always

    ports:
      - "8080:8080"

    env_file:
      - ./open-webui.env
      - ./open-webui-azure-db.env

    volumes:
      - /opt/open-webui/data:/app/backend/data

持久化 OpenWebUI 本地文件

迁移前，OpenWebUI 的 /app/backend/data 没有挂载到宿主机。

先将数据复制出来：

sudo install \
  -d \
  -m 700 \
  -o "$(id -un)" \
  -g "$(id -gn)" \
  /opt/open-webui/data

docker cp \
  open-webui:/app/backend/data/. \
  /opt/open-webui/data/

在 Compose 中加入：

volumes:
  - /opt/open-webui/data:/app/backend/data

这样，即使未来重建或升级 OpenWebUI 容器，以下内容仍会保留：

• 上传文件
• 向量数据库
• 缓存
• 其他本地应用数据

迁移后验证：

docker inspect open-webui \
  --format '{{range .Mounts}}{{println .Source "->" .Destination "rw=" .RW}}{{end}}'

预期：

/opt/open-webui/data -> /app/backend/data rw=true

迁移后的验证

1. OpenWebUI 健康检查

curl \
  -sS \
  -o /dev/null \
  -w 'HTTP %{http_code}\n' \
  --max-time 10 \
  http://127.0.0.1:8080/health

预期：

HTTP 200

2. 验证 OpenWebUI 当前数据库

为了避免输出密码，只解析连接串中的非敏感部分：

docker exec -i open-webui python3 - <<'PY'
import os
from urllib.parse import urlsplit

u = urlsplit(os.environ["DATABASE_URL"])

print("Database host configured:", bool(u.hostname))
print("Database port:", u.port)
print("TLS required:", "sslmode=require" in u.query)
PY

验证重点：

• Host 已不再指向 VM 本地 PostgreSQL
• 端口为 5432
• 已启用 sslmode=require

3. 检查启动日志

docker logs \
  --since 15m \
  open-webui 2>&1 |
grep -Ei \
  'error|fatal|exception|traceback|permission denied|database|postgres|alembic|ssl|timeout'

正常情况下只会看到类似：

INFO [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO [alembic.runtime.migration] Will assume transactional DDL.

不应出现：

• 数据库连接失败
• 密码认证失败
• TLS 错误
• Schema 权限错误
• Alembic 迁移失败
• Python Traceback

卸载 VM 本地 PostgreSQL

确认 OpenWebUI 已稳定连接 Azure PostgreSQL 后，可以删除 VM 上的本地 PostgreSQL。

首先确认：

• OpenWebUI 健康检查正常
• 数据库连接已切换
• Azure PostgreSQL 中存在最新数据
• 自动备份策略已经启用
• 本地 PostgreSQL 不再有应用连接

停止并删除本地集群：

sudo pg_dropcluster \
  --stop \
  <POSTGRESQL_VERSION> \
  main

卸载 PostgreSQL 服务端：

sudo apt-get purge -y \
  postgresql \
  postgresql-<POSTGRESQL_VERSION> \
  postgresql-contrib

删除遗留数据和配置：

sudo rm -rf \
  /var/lib/postgresql \
  /etc/postgresql \
  /var/log/postgresql

可以继续保留 PostgreSQL 客户端：

postgresql-client
postgresql-client-common

这样仍然可以从 VM 使用 psql 管理 Azure PostgreSQL。

最终检查本地 5432：

if sudo ss -lntp | grep -q ':5432'; then
  sudo ss -lntp | grep ':5432'
else
  echo "No local PostgreSQL listener"
fi

迁移过程中的经验总结

1. 数据库迁移不等于 OpenWebUI 全部数据迁移

OpenWebUI 除了 PostgreSQL，还可能在 /app/backend/data 中保存：

• 上传文件
• 向量数据库
• 缓存
• 本地状态文件

只执行 pg_dump 并不能迁移这些内容。

2. 不要只测试端口连通

nc 成功只能证明 TCP 5432 可达，并不能证明：

• PostgreSQL 用户可以登录
• 密码正确
• TLS 正常
• 数据库权限正确
• OpenWebUI 使用的驱动兼容

应至少完成以下验证：

DNS → TCP → PostgreSQL 登录 → TLS → SQL 查询 → OpenWebUI 实际连接

3. 数据库 owner 不代表一定拥有 schema 创建权限

即使应用用户是数据库 owner，也可能遇到：

permission denied for schema public

迁移前应验证应用账号是否具备：

• USAGE
• CREATE
• 表和序列所有权
• Alembic DDL 权限

4. 在线全量备份后必须处理增量写入

pg_dump 提供的是开始备份时的一致性快照。

备份期间 OpenWebUI 新产生的对话和消息不会自动进入已经完成的 dump。因此在线迁移必须增加以下机制之一：

• 最终停写后重新完整备份
• 逻辑复制
• CDC
• 应用双写
• 按业务对象执行增量同步

本次采用的是“全量快照 + 活跃对话 UPSERT”。

5. 不要在迁移时顺便升级 OpenWebUI

本次迁移始终保持 OpenWebUI 镜像版本不变。

如果同时升级应用和迁移数据库，一旦发生问题，很难快速判断原因来自：

• PostgreSQL 版本
• 数据迁移
• Azure 网络
• 数据库权限
• OpenWebUI 版本
• Alembic schema 变化

更稳妥的做法是：

先迁移数据库并稳定运行
          ↓
再单独升级 OpenWebUI

这算不算真正的零停机？

从用户体验看，这次迁移接近零停机：

• 在线完成全量备份
• 在线恢复目标数据库
• 在线完成数据验证
• 在线同步活跃对话
• 仅在最后重建了一次 OpenWebUI 容器

但如果采用严格工程定义，真正的零停机还需要满足：

• 任意时刻都能接受新连接
• 最后时刻写入绝不丢失
• 没有单实例容器重启窗口
• 客户端连接完全不中断
• 具备自动流量切换能力

更大规模的 OpenWebUI 部署可以考虑：

• PostgreSQL 逻辑复制
• Azure Database Migration Service
• CDC 增量迁移
• 应用双写
• 蓝绿部署
• 多个 OpenWebUI 实例
• 反向代理健康检查
• 连接排空和流量切换

对于单 VM、单 OpenWebUI 容器和中小规模数据库，本次采用的方案在复杂度、风险和停机时间之间取得了较好的平衡。

迁移后的日常运维

启动 OpenWebUI：

docker compose \
  -f run-with-azure-pg.yml \
  up -d

查看状态：

docker compose \
  -f run-with-azure-pg.yml \
  ps

查看日志：

docker compose \
  -f run-with-azure-pg.yml \
  logs -f --tail=200

健康检查：

curl \
  -sS \
  -o /dev/null \
  -w 'HTTP %{http_code}\n' \
  http://127.0.0.1:8080/health

日常还应重点监控 Azure PostgreSQL 的：

• CPU 使用率
• 内存使用情况
• 存储空间
• 活跃连接数
• 失败连接数
• 查询延迟
• 自动备份状态
• 维护事件
• Private Endpoint 状态

总结

这次迁移将 OpenWebUI 的数据库从 Azure VM 自建 PostgreSQL 平滑迁移到了 Azure Database for PostgreSQL Flexible Server。

最终实现了：

• OpenWebUI 数据库由 Azure 托管
• 通过 Private Endpoint 私网访问
• 数据库连接启用 TLS
• 自动备份和时间点恢复
• OpenWebUI 本地文件持久化
• VM 本地 PostgreSQL 完全下线
• 本地 5432 端口关闭
• 全量迁移期间应用持续在线
• 最终切换对用户影响极低

本次最关键的经验是：

对 OpenWebUI 进行低停机数据库迁移，不应只关注 pg_dump 和 pg_restore，还必须同时考虑增量写入、Private Endpoint、TLS、数据库权限、Alembic 迁移以及 /app/backend/data 中的本地文件。

通过“在线全量迁移、目标端预验证、活跃数据增量同步、快速容器切换”，可以在不引入复杂 CDC 平台的情况下，将中小规模 OpenWebUI 平滑迁移到 Azure 托管 PostgreSQL。