安装部署¶

架构¶

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

                    HTTPS :8443（vConfig 自终结 TLS）
  运维人员 ──────────────► app（vConfig，gunicorn 单进程）
                              │           │
                              │           ├── app_data 卷：证书、密钥、
                              │           │   配置归档、许可证
                              ▼           │
                            db（MariaDB 11，db_data 卷）

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

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

系统要求与容量规划¶

被管设备数	CPU	内存	磁盘	说明
≤ 100（Free/Pro）	2 vCPU	4 GB	40 GB	小型虚机即可
≤ 1,000（Business）	4 vCPU	8 GB	100 GB	建议调大备份并发
≤ 10,000（Scale）	8 vCPU	16 GB	300 GB+	强烈建议 SSD

操作系统：Ubuntu 22.04/24.04、Debian 12、RHEL 9（x86_64）。未装 Docker 时自动安装。
磁盘随配置历史、盘点快照、监控样本与 syslog 量增长。配置归档压缩率高；繁忙设备开启日志洞察时请预留充足空间。
vConfig 有意采用单应用进程（保证调度一致性）；扩容请纵向加配置（更大的虚机），不要横向加实例。

网络 / 防火墙矩阵¶

方向	端口	用途
入（运维 → vConfig）	TCP 8443（可改）	Web UI / API，TLS
出（vConfig → 设备）	TCP 22、23	SSH/Telnet：备份、盘点、SLA 探测、终端
出（vConfig → 设备）	UDP 161	SNMP 发现与指标
出（vConfig → 设备）	ICMP	可达性探测
入（设备 → vConfig）	UDP 514（可选）	syslog 供日志洞察
出（vConfig → vconfig.ai）	TCP 443	许可证激活、OTA 更新检查

一键安装¶

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

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

安装器会：

安装 Docker（如缺失）。
下载最新发行镜像并校验 SHA-256。
在 /opt/vconfig/.env 生成随机数据库凭据（权限 600）。
写入 docker-compose.yml 并启动 app + db。
首启自动生成自签名 TLS 证书。
打印访问地址与初始管理员密码，并安装 vconfigctl 运维工具。

安装器选项¶

变量	默认值	含义
`VCONFIG_DIR`	`/opt/vconfig`	安装目录
`VCONFIG_PORT`	`8443`	主机对外 HTTPS 端口

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

首次登录¶

打开 https://<你的服务器>:8443，接受自签证书提示，用打印的密码以 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 前也会自动执行。请按你的策略把 /opt/vconfig/backups 异地保存——灾难恢复所需的一切都在里面。

安全加固清单¶

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

升级、回滚、卸载¶

vconfigctl update --check   # 检查新版本
vconfigctl update           # 自动备份后原地升级（停机 <30 秒）
vconfigctl status           # 容器状态 + 当前版本

回滚：把 /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]。