安装部署¶

架构¶

一套 vConfig 安装 = Docker Compose 管理的六个容器 + 数据卷：

                    HTTPS :443（vConfig 自终结 TLS；:80 自动 301 跳转）
  运维人员 ──────────────► app（Web，gunicorn 单进程）
                    │         │  └── 进程内 syslog 接收器（:514）
                    │         │
                    │         ├── prometheus ┐ 与 app 共用网络命名空间，
                    │         └── snmp-exporter ┘ 所以产品默认的 127.0.0.1:9090
                    │                            / :9116 无需任何配置就成立
                    │
  Web 终端 :8443 ──► gateway（堡垒机会话网关：WebSocket + SSH 代理 + 录像）
                              ai-worker（AIOps 事件分析与处置，独立于 Web）
                              db（MariaDB 11）

  app / gateway ── SSH :22 / Telnet :23 / SNMP :161 / ICMP ──► 你的网络设备
  app ── HTTPS :443 ──► vconfig.ai （仅许可证激活 + 更新检查）
  设备 ── syslog :514/UDP ──► app （供日志洞察）

全部跑在一台主机上，vconfigctl status 一次看六个服务。设备侧无需安装任何 Agent——vConfig 像运维人员一样通过 SSH/Telnet/SNMP 访问设备。

Prometheus 与 snmp-exporter 只在主机内部可达，不对外暴露端口；采集目标由 vConfig 自动写入共享卷里的 file_sd 文件，加删设备无需手工改采集配置。

系统要求与容量规划¶

	最低配置	推荐配置
操作系统	Ubuntu 24.04 LTS（x86_64）	Ubuntu 24.04 LTS（x86_64）
CPU	4 vCPU	8 vCPU
内存	8 GB	16 GB
磁盘	500 GB+	1 TB+，建议 SSD

未装 Docker 时安装脚本会自动装好，共拉起六个容器：应用、网关、AI 工作进程、数据库、Prometheus、snmp-exporter。
磁盘是最容易低估的一项：配置历史、盘点快照、监控样本、syslog 与 NetFlow 流量记录都在持续增长，而后三项随设备数和采样率线性上升。配置归档压缩率很高，真正吃盘的是日志与流量。开启日志洞察或流量分析的现场请按上表的推荐值起步。
上面给的是整机要求，不按设备数分档：监控与日志的开销主要来自采集频率和保留期，而不只是设备台数。1000 台只做配置备份的现场，可能比 100 台开满流量分析的现场轻得多。
vConfig 有意采用单应用进程（保证调度一致性）；扩容请纵向加配置（更大的虚机），不要横向加实例。

网络 / 防火墙矩阵¶

方向	端口	用途
入（运维 → vConfig）	TCP 443（可改）	Web UI / API，TLS
入（运维 → vConfig）	TCP 80	仅 301 跳转到 HTTPS；被占用时安装脚本自动跳过
入（运维 → vConfig）	TCP 8443（可改）	Web 终端与堡垒机会话（浏览器 WebSocket）
入（设备 → vConfig）	UDP/TCP 514	syslog，供日志洞察。默认不开启——在「设置 → Syslog」打开后再把设备指过来；514 被宿主机 rsyslog 占用时安装脚本自动改用 1514
入（设备 → vConfig）	UDP 2055	流量分析：NetFlow v5/v9、IPFIX、sFlow 共用这一个端口。默认不开启——在「可视化 → 流量分析 → 采集设置」打开。设备侧务必开采样（1:1000 起步），不采样的繁忙路由器会把采集器淹掉
入（设备 → vConfig）	TCP 21（可改）	镜像分发：设备用 `copy ftp://…` 来取固件的控制连接。仅在用「堡垒机 → 镜像仓库」推固件时才需要；21 被占用时安装脚本改发布 2121（注意：部分老交换机会忽略自定义端口）
入（设备 → vConfig）	TCP 50100-50140	镜像分发：FTP 被动模式数据口。范围刻意收窄，便于在防火墙上交代
入（设备 → vConfig）	TCP 2222（可改）	镜像分发：内置 SCP 源（22 是宿主机 sshd 的，抢不了）
出（vConfig → 设备）	TCP 22、23	SSH/Telnet：备份、盘点、SLA 探测、终端
出（vConfig → 设备）	UDP 161	SNMP 发现与指标
出（vConfig → 设备）	ICMP	可达性探测
出（vConfig → vconfig.ai）	TCP 443	许可证激活、OTA 更新检查
出（vConfig → 邮件服务器）	TCP 587（可改）	邮件告警；仅在「设置 → 告警」里配了 SMTP 时才用到
出（vConfig → LDAP 服务器）	TCP 389 / 636	LDAP/LDAPS 登录；仅在启用 LDAP 认证时才用到
出（vConfig → 云商 API）	TCP 443	多云资源采集；仅在添加了云账号时才用到

日常只需对运维网开 443、80 与 8443；Prometheus(9090) 与 snmp-exporter(9116) 只在主机内部监听，不需要也不应该放行。

镜像分发那三行只在从界面往设备推固件时才用得上，且只需对设备网段开放。不用这个功能就整块不开，装机时加 VCONFIG_TRANSFER_PORTS=0 连端口都不发布。

容器部署：设备回连地址

容器里只看得到 172.x 的容器地址，机房里的交换机连不上它。安装脚本会把宿主机地址注入容器（VCONFIG_ADVERTISE_IP），生成的 copy 命令与 FTP 被动模式回应都用它。宿主机有多个地址、而设备只能走其中一个时，用 VCONFIG_ADVERTISE_IP=<该地址> 装机，或装完在「设置 → 镜像仓库 → 设备回连地址」里改，改完立即生效。

一键安装¶

在干净的服务器上以 root 执行：

curl -fsSL https://vconfig.ai/install.sh | sudo bash

安装器会：

安装 Docker（如缺失）。
腾出 80/443：被 nginx/apache 等占用时会停掉它们并记录到 /opt/vconfig/ports-freed.txt——装完想恢复得有据可查。
下载最新发行镜像并校验 SHA-256；依赖镜像（MariaDB / Prometheus / snmp-exporter）连得上 Docker Hub 就直接拉，连不上则从 vconfig.ai 下载依赖包——后者才是运营商、IDC 与中国大陆网络的常态。
在 /opt/vconfig/.env 生成随机数据库凭据（权限 600）。
写入 docker-compose.yml 并启动六个容器：app（Web/API/采集）、gateway（Web 终端与堡垒机）、ai-worker（AI 分析）、db（MariaDB）、prometheus、snmp-exporter。
首启自动生成自签名 TLS 证书。
打印访问地址、初始管理员密码与需要在防火墙上放行的端口清单，并安装 vconfigctl 运维工具。

安装完成后跑一次 vconfigctl status 可以确认六个容器都起来了；密码丢了用 vconfigctl password 取回（改过密码后该文件会被删除，取不到属正常）。

安装器选项¶

变量	默认值	含义
`VCONFIG_DIR`	`/opt/vconfig`	安装目录
`VCONFIG_PORT`	`443`	主机对外 HTTPS 端口
`VCONFIG_HTTP_PORT`	`80`	HTTP 跳转端口，置空则不发布
`VCONFIG_GW_PORT`	`8443`	Web 终端 / 堡垒机会话端口
`VCONFIG_SYSLOG_PORT`	`514`	接收设备 syslog 的主机端口（被占用时自动改 1514）
`VCONFIG_NETFLOW_PORTS`	`1`	是否发布流量分析端口。`0` = 不发布
`VCONFIG_NETFLOW_PORT`	`2055`	流量采集端口（NetFlow v5/v9、IPFIX、sFlow 共用一个 UDP 端口，按报文首部自动识别）
`VCONFIG_TRANSFER_PORTS`	`1`	是否发布镜像分发端口（FTP/SCP）。`0` = 都不发布
`VCONFIG_FTP_PORT`	`21`	镜像分发 FTP 控制端口（被占用时自动改 2121）
`VCONFIG_FTP_PASV_MIN` / `_MAX`	`50100` / `50140`	FTP 被动数据端口范围
`VCONFIG_SCP_PORT`	`2222`	内置 SCP 源端口（被占用时自动改 2223）
`VCONFIG_ADVERTISE_IP`	宿主机首个地址	告诉设备来哪个地址取镜像
`VCONFIG_SNMP_COMMUNITY`	`public`	写入 snmp-exporter 配置的默认 community

示例：curl -fsSL https://vconfig.ai/install.sh | sudo VCONFIG_PORT=443 bash

首次登录¶

打开 https://<你的服务器>（默认 443，http:// 会自动 301 跳转），接受自签证书提示，用打印的密码以 admin 登录——首登强制改密。然后按快速上手继续。

使用自己的 TLS 证书

在 设置 → 证书 上传 CA 签发的证书；内置 HTTP→HTTPS 跳转。如果你前置了自己的反向代理，请转发到 HTTPS 端口并保留 Host 头。

数据位置与备份¶

路径 / 卷	内容
`vconfig_app_data` 卷（`/app/data`）	TLS 证书、加密密钥、许可证、配置归档、设置
`vconfig_db_data` 卷	MariaDB（设备台账、用户、监控历史、日志）
`/opt/vconfig/.env`	数据库凭据、当前版本
`/opt/vconfig/backups/`	`vconfigctl backup` 的输出

vconfigctl backup 一次性导出数据库并归档数据卷；每次 vconfigctl update 前也会自动执行。该目录默认只保留最近 5 份，更早的会自动删除（VCONFIG_KEEP_BACKUPS=份数 可调）——正因如此，请按你的策略把 /opt/vconfig/backups 异地保存，灾难恢复所需的一切都在里面。

安全加固清单¶

用安全组/防火墙把 TCP 443 与 8443 限制到运维网段。
按人建账号、按角色授权（管理员/运维/只读）并限定设备分组；admin 仅留作应急。
设备侧使用专用自动化账号；vConfig 以 Fernet 加密存储。
ssh_known_hosts 收集齐后，在 设置 → 备份 开启 SSH 主机密钥严格校验。
设备发 syslog 时，UDP 514 仅对设备管理网段开放。

升级、回滚、卸载¶

vconfigctl update --check   # 检查新版本
vconfigctl update           # 自动备份后原地升级（停机 <30 秒）
vconfigctl status           # 容器状态 + 当前版本
vconfigctl prune            # 手动清理旧升级包/镜像与旧备份

回滚：把 /opt/vconfig/.env 中 VCONFIG_VERSION= 改回上一版本后 docker compose up -d；若新版已迁移数据库结构，同时恢复对应的数据库备份。升级成功后会自动清理：升级包与镜像各只保留当前版和上一版（回滚要用），更早的自动删除。

彻底卸载（删除全部数据！）：

cd /opt/vconfig && docker compose down -v && cd / && rm -rf /opt/vconfig

离线 / 隔离网络环境¶

激活需要 HTTPS 访问 vconfig.ai，可容忍 14 天离线。完全隔离网络可用企业版离线激活与手工镜像传输——联系 [email protected]。