Ubuntu 22.04 安装 GNS3 2.2.61 服务端指南
在 Ubuntu 22.04.5 上以 venv+pip、离线 wheel、官方 PPA 三方案安装 GNS3 2.2.61 服务端：QEMU/libvirt/Dynamips/VPCS 依赖、/etc/gns3 配置、systemd 托管、3080 端口与 Web UI 验证，并实测 KVM 不可用时的 -accel tcg 降级与性能代价。
Ubuntu 22.04 安装 GNS3 2.2.61 服务端指南
目标：在 Ubuntu 22.04 LTS 上从零安装 GNS3 2.2.61 服务端（gns3-server），补齐 QEMU、libvirt、Dynamips、VPCS 等节点后端依赖，用 systemd 托管并监听 3080 端口，最后验证 REST 接口可用。本文所有命令与回显均来自 Ubuntu 22.04.5 LTS + Python 3.10.12 实测环境；GNS3 的 controller/compute 架构与选型结论见 《GNS3 2.2.61 介绍与选型指南》。
一、环境信息与前置条件
本节的目的是把「装的到底是什么版本、跑在什么系统上」先钉死，避免后续命令因版本差异对不上。GNS3 2.2.x 是一条仍在维护的稳定分支（2026-07-30 发布了 2.2.61），与 3.x 分支并行存在；本文只针对 2.2.61。
1.1 实测环境
| 项目 | 实测值 | 说明 |
|---|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS | jammy，官方支持 Python 3.10 |
| 内核 | 7.0.0-38-generic x86_64 | 实测宿主内核版本 |
| Python | 3.10.12 | 系统自带，GNS3 2.2.61 要求 >=3.9 |
| 服务端版本 | gns3-server 2.2.61 | PyPI 2026-07-30 上传 |
| 服务端口 | 3080/tcp | gns3-server 默认端口 |
| 硬件虚拟化 | 不可用（KVM 模块访问失败） | 见第八章降级方案 |
系统与 Python 版本核对：
cat /etc/os-release | head -2
python3 -V
PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
Python 3.10.12
1.2 前置条件
- 一台可联网的 Ubuntu 22.04 服务器，具备
sudo或 root 权限；本文全部操作以root执行，演示登录账号为root/q1w2e3r4。 - 至少 2 核 CPU、4 GB 内存、20 GB 磁盘（QEMU 节点后端与 IOS 映像文件都占空间）。
- 3080/tcp 未被占用；如需从外部访问，还需放行该端口。
- 若要用 QEMU 节点跑真实系统，需要宿主开放
/dev/kvm；本文实测环境未开放，已在第八章给出降级路线。
端口占用情况先自查一次，避免装完才发现端口冲突：
ss -ltnp | grep 3080 || echo "3080 未被占用"
3080 未被占用
1.3 版本选型说明
GNS3 2.2.x 与 3.x 是两条并行分支，官方在 2026 年仍在给 2.2.x 打补丁版本；2.2.61 是 2.2 分支当前最新的稳定包。选 2.2.61 的理由是：桌面客户端、Web UI、REST API（/v2）生态成熟，社区模板与 appliance 定义齐全；3.x 的接口与数据模型有变化，第三方模板兼容性还在补齐。
服务端包名与版本可直接在 PyPI 上核对（本文安装前实测）：
curl -s https://pypi.org/pypi/gns3-server/json | python3 -c "import sys,json;d=json.load(sys.stdin);print(d['info']['version']);print([k for k in d['releases'] if k.startswith('2.2.6')])"
3.0.6
['2.2.60', '2.2.61']
输出说明：PyPI 上的 info.version 取的是该包最新发布（3.0.6），2.2 分支的尾部版本是 2.2.60 与 2.2.61，因此安装时必须显式锁定 ==2.2.61，否则会装到 3.x。
二、安装方案 A：venv + pip 在线安装（推荐）
2.1 方案说明
这是 GNS3 官方在 Linux 上推荐的部署形态之一：把 gns3-server 装进独立的 Python 虚拟环境，不污染系统 Python，也便于 2.2.x/3.x 多版本并存与回滚。优点是版本可控（可精确到 2.2.61）、升级即换 venv；缺点是需要联网拉取依赖，内网环境要走第三章的离线方案。
2.2 安装系统依赖
gns3-server 本身只是调度层，真正的节点运行靠 QEMU、Dynamips、VPCS 等外部程序，libvirt 负责 QEMU 的部分网络与生命周期管理。先把这些依赖一次性装好：
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y \
python3-venv python3-pip curl \
qemu-system-x86 qemu-utils libvirt-daemon-system libvirt-clients \
bridge-utils dynamips vpcs
安装输出较长，节选（实测首尾）：
Reading package lists...
Building dependency tree...
Reading state information...
The following additional packages will be installed:
acl adwaita-icon-theme alsa-topology-conf alsa-ucm-conf at-spi2-core
cpu-checker dbus-user-session dconf-gsettings-backend dconf-service dmeventd
...
Processing triggers for libgdk-pixbuf-2.0-0:amd64 (2.42.8+dfsg-1ubuntu0.5) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...
各依赖的作用与实测版本（dpkg -l 查询）：
dpkg -l qemu-system-x86 libvirt-daemon-system dynamips vpcs python3-venv | grep ^ii | awk '{print $2, $3}'
dynamips 0.2.14-1build1
libvirt-daemon-system 8.0.0-1ubuntu7.21
python3-venv 3.10.6-1~22.04.1
qemu-system-x86 1:6.2+dfsg-2ubuntu6.31
vpcs 0.5b2-2.2
qemu-system-x86：QEMU 节点后端，可跑路由器/交换机/主机类虚拟机节点。libvirt-daemon-system：提供libvirtd与默认 NAT 网桥virbr0，GNS3 的 NAT 节点依赖它。dynamips：Cisco IOS 传统模拟后端，2.2 分支仍保留。vpcs：轻量 PC 节点，只发不收的连通性验证常用。python3-venv：创建隔离的 Python 环境。
验证依赖真的可执行：
qemu-system-x86_64 --version | head -1
dynamips -h 2>&1 | head -2
vpcs -v 2>&1 | head -2
systemctl is-active libvirtd
QEMU emulator version 6.2.0 (Debian 1:6.2+dfsg-2ubuntu6.31)
Cisco Router Simulation Platform (version 0.2.14-amd64/Linux stable)
Copyright (c) 2005-2011 Christophe Fillot.
Welcome to Virtual PC Simulator, version 0.5b2
active
2.3 VPCS 与 uBridge 的版本门槛（容易漏装）
上面装完就以为依赖齐了，实际还差两步——这是实测最容易卡住的地方：
-
VPCS 版本过旧。Ubuntu 22.04 仓库自带
0.5b2，GNS3 2.2.61 要求 ≥0.6.1，启动 VPCS 节点会直接返回：{"message": "VPCS executable version must be >= 0.6.1 but not a 0.8", "status": 409}注意报错里"but not a 0.8"是历史文案，实测 0.8.4 完全可用，按 ≥0.6.1 判断即可。
-
uBridge 缺失。它是节点间链路（虚拟交换机侧）的桥接程序，Ubuntu 主线仓库没有这个包，缺了之后启动任何带链路的节点都会失败：
uBridge is not available, path doesn't exist, or you just installed GNS3 and need to restart your user session to refresh user permissions.
两个都用 GNS3 官方 PPA 补齐：
add-apt-repository -y ppa:gns3/ppa
apt-get update
apt-get install -y vpcs ubridge
vpcs -v | head -2
ubridge version
Welcome to Virtual PC Simulator, version 0.8.4
Dedicated to Daling.
uBridge version 0.9.19 running with libpcap version 1.10.1 (with TPACKET_V3)
装完确认版本真的被覆盖（apt-cache policy 应显示 PPA 的候选版本）：
apt-cache policy vpcs | head -4
vpcs:
Installed: 1:0.8.4-1~jammy1
Candidate: 1:0.8.4-1~jammy1
💡 技术拓展：PPA 里的
gns3-server版本是2.2.55~jammy2，不是 2.2.61。所以 PPA 只用来补vpcs/ubridge这类外围工具，服务端本体仍走 pip 固定版本，两者不要混用。
2.4 创建虚拟环境并安装 gns3-server 2.2.61
把运行目录统一收敛到 /opt/gns3，配置放 /etc/gns3，数据放 /var/lib/gns3，日志放 /var/log/gns3，后续所有命令都基于这套路径：
python3 -m venv /opt/gns3/venv
/opt/gns3/venv/bin/pip install --upgrade pip
/opt/gns3/venv/bin/pip install gns3-server==2.2.61
mkdir -p /etc/gns3 /var/lib/gns3/projects /var/lib/gns3/images \
/var/lib/gns3/appliances /var/lib/gns3/symbols /var/log/gns3
安装回显（实测节选）：
Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple
Collecting gns3-server==2.2.61
Downloading gns3_server-2.2.61-py3-none-any.whl (14.7 MB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 14.7/14.7 MB 2.3 MB/s 0:00:06
Collecting jsonschema<4.27,>=4.26.0 (from gns3-server==2.2.61)
Collecting aiohttp<3.14,>=3.13.5 (from gns3-server==2.2.61)
...
Installing collected packages: py-cpuinfo, urllib3, typing-extensions, truststore, rpds-py, psutil, propcache, platformdirs, MarkupSafe, idna, frozenlist, distro, certifi, attrs, async-timeout, aiohappyeyeballs, aiofiles, sentry-sdk, referencing, multidict, Jinja2, aiosignal, yarl, jsonschema-specifications, jsonschema, aiohttp, aiohttp-cors, gns3-server
Successfully installed Jinja2-3.1.6 MarkupSafe-3.0.4 aiofiles-25.1.0 aiohappyeyeballs-2.7.1 aiohttp-3.13.5 aiohttp-cors-0.8.1 aiosignal-1.4.0 async-timeout-5.0.1 attrs-26.1.0 certifi-2026.10.23 distro-1.9.0 frozenlist-1.8.0 gns3-server-2.2.61 idna-3.20 jsonschema-4.26.0 jsonschema-specifications-2025.9.1 multidict-6.9.1 platformdirs-2.6.2 propcache-0.5.4 psutil-7.2.2 py-cpuinfo-9.0.0 referencing-0.37.0 rpds-py-0.30.0 sentry-sdk-2.73.0 truststore-0.10.5 typing-extensions-4.16.0 urllib3-2.8.0 yarl-1.25.1
⚠️ 网络说明：直连 pypi.org 在本环境下载 14.7 MB 主包时长时间无进展，改用清华软件源 -i https://pypi.tuna.tsinghua.edu.cn/simple 后稳定在 2.3 MB/s。国内环境建议按「官方源 → 国内源 → 代理」的顺序降级；能直连官方源时无需加 -i 参数。
2.5 版本验证
安装完先确认落地版本与依赖树完整，再谈配置：
/opt/gns3/venv/bin/gns3server --version
/opt/gns3/venv/bin/pip show gns3-server | head -4
2.2.61
Name: gns3-server
Version: 2.2.61
Summary: GNS3 server
Home-page: http://github.com/GNS3/gns3-server
2.6 命令参数速查
gns3server 的参数不多，但排查端口/日志问题时都用得上（实测 --help 输出节选）：
usage: gns3server [-h] [-v] [--host HOST] [--port PORT] [--ssl]
[--config CONFIG] [--certfile CERTFILE] [--certkey CERTKEY]
[--record RECORD] [-L] [-A] [-q] [-d] [--shell] [--log LOG]
[--logmaxsize LOGMAXSIZE] [--logbackupcount LOGBACKUPCOUNT]
[--logcompression] [--daemon] [--pid PID]
[--profile PROFILE]
| 参数 | 作用 | 本文取值 |
|---|---|---|
--config | 指定配置文件 | /etc/gns3/gns3_server.conf |
--host / --port | 覆盖监听地址与端口 | 配置文件中固定为 0.0.0.0 / 3080 |
--log | 把日志写入文件而非标准输出 | /var/log/gns3/gns3_server.log |
--logmaxsize / --logbackupcount | 单个日志上限（默认 10MB）与保留个数（默认 10） | 未改动 |
--daemon / --pid | 后台运行并写 pid 文件 | 未使用（交给 systemd） |
-L, --local | 本地模式，放开部分不安全操作 | 未使用 |
-q / -d | 静默 / 调试日志 | 排障时用 -d |
三、安装方案 B：离线 wheel 包安装
3.1 方案说明
内网服务器无法访问 PyPI 时，可以在能联网的机器上把 2.2.61 及其全部依赖下载成 wheel，再整体拷进目标机离线安装。这条路线同样能精确锁定 2.2.61，且安装过程不需要联网。
3.2 联网机下载 wheel 包
mkdir -p /opt/gns3/wheels
/opt/gns3/venv/bin/pip download -i https://pypi.tuna.tsinghua.edu.cn/simple \
-d /opt/gns3/wheels gns3-server==2.2.61
Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple
Collecting gns3-server==2.2.61
Using cached gns3_server-2.2.61-py3-none-any.whl (14.7 MB)
Collecting jsonschema<4.27,>=4.26.0 (from gns3-server==2.2.61)
产物清单与体积：
du -sh /opt/gns3/wheels
ls /opt/gns3/wheels | wc -l
ls /opt/gns3/wheels | head -5
19M /opt/gns3/wheels
28
aiofiles-25.1.0-py3-none-any.whl
aiohappyeyeballs-2.7.1-py3-none-any.whl
aiohttp-3.13.5-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
aiohttp_cors-0.8.1-py3-none-any.whl
aiosignal-1.4.0-py3-none-any.whl
共 28 个 wheel、19 MB。把整个 /opt/gns3/wheels 目录拷到离线机同一路径即可。
3.3 离线机安装
python3 -m venv /opt/gns3/venv-offline
/opt/gns3/venv-offline/bin/pip install --no-index --find-links /opt/gns3/wheels gns3-server==2.2.61
Processing /opt/gns3/wheels/idna-3.20-py3-none-any.whl
Installing collected packages: py-cpuinfo, urllib3, typing-extensions, truststore, rpds-py, psutil, propcache, platformdirs, MarkupSafe, idna, frozenlist, distro, certifi, attrs, async-timeout, aiohappyeyeballs, aiofiles, sentry-sdk, referencing, multidict, Jinja2, aiosignal, yarl, jsonschema-specifications, jsonschema, aiohttp, aiohttp-cors, gns3-server
Successfully installed Jinja2-3.1.6 MarkupSafe-3.0.4 aiofiles-25.1.0 aiohappyeyeballs-2.7.1 aiohttp-3.13.5 aiohttp-cors-0.8.1 aiosignal-1.4.0 async-timeout-5.0.1 attrs-26.1.0 certifi-2026.10.23 distro-1.9.0 frozenlist-1.8.0 gns3-server-2.2.61 idna-3.20 jsonschema-4.26.0 jsonschema-specifications-2025.9.1 multidict-6.9.1 platformdirs-2.6.2 propcache-0.5.4 psutil-7.2.2 py-cpuinfo-9.0.0 referencing-0.37.0 rpds-py-0.30.0 sentry-sdk-2.73.0 truststore-0.10.5 typing-extensions-4.16.0 urllib3-2.8.0 yarl-1.25.1
--no-index 强制 pip 不访问任何网络源，--find-links 指向本地目录，因此这条路线可以在完全断网的机器上跑通。版本确认：
/opt/gns3/venv-offline/bin/gns3server --version
2.2.61
/opt/gns3 下同时存在 venv 与 venv-offline 两套环境，实际投产只用其中一套；多环境并存时 systemd 单元的 ExecStart 写哪一套，服务就跑哪一套。
四、安装方案 C：官方 PPA 仓库安装（版本受限）
4.1 方案说明
GNS3 官方维护了 Ubuntu PPA（ppa:gns3/ppa），适合希望用 apt 统一管理、自动跟随仓库更新的场景。但它有一个必须先核对的现实问题：仓库里的版本未必是最新的 2.2.61。
4.2 添加 PPA 并核对候选版本
DEBIAN_FRONTEND=noninteractive apt-get install -y software-properties-common
add-apt-repository -y ppa:gns3/ppa
apt-get update
apt-cache policy gns3-server
添加仓库时的回显（实测）：
Get:5 https://ppa.launchpadcontent.net/gns3/ppa/ubuntu jammy InRelease [18.3 kB]
Get:6 https://ppa.launchpadcontent.net/gns3/ppa/ubuntu jammy/main amd64 Packages [2084 B]
Repository: 'deb https://ppa.launchpadcontent.net/gns3/ppa/ubuntu/ jammy main'
PPA for GNS3 v2.x and supporting packages. Please see http://www.gns3.com for more details.
候选版本查询结果（实测，关键结论）：
gns3-server:
Installed: (none)
Candidate: 2.2.55~jammy2
Version table:
2.2.55~jammy2 500
500 https://ppa.launchpadcontent.net/gns3/ppa/ubuntu jammy/main amd64 Packages
⚠️ 结论：截至实测时间，jammy 的 PPA 仓库里 gns3-server 候选版本是 2.2.55~jammy2，没有 2.2.61。若必须使用 2.2.61，请用方案 A 或方案 B；如果只是要一个能跑 2.2 分支的稳定服务端、且愿意接受 2.2.55，则 apt-get install -y gns3-server 即可，安装后由发行包自带的服务单元托管。
五、方案对比与选择建议
三条路线各有取舍，先看横向对比再决定：
| 维度 | 方案 A：venv + pip | 方案 B：离线 wheel | 方案 C：官方 PPA |
|---|---|---|---|
| 可获得版本 | 2.2.61（精确锁定） | 2.2.61（精确锁定） | 实测仅 2.2.55~jammy2 |
| 是否需联网 | 安装时需联网 | 仅准备阶段需联网 | 安装时需联网 |
| 依赖隔离 | 独立 venv，干净 | 独立 venv，干净 | 装入系统 Python，可能与系统包互相影响 |
| 升级/回滚 | 新建 venv 切换即可 | 换 wheel 目录重装 | apt upgrade 跟随仓库 |
| systemd 单元 | 需自行编写 | 需自行编写 | 包内自带 |
| 适用场景 | 生产首选，要 2.2.61 | 内网隔离环境 | 只求 2.2 分支、能接受旧补丁 |
选择建议：需要 2.2.61 一律走 A（联网）或 B（离线）；只有对版本不敏感、且希望少维护服务单元时才考虑 C，并接受 2.2.55。
六、服务端配置与 systemd 托管
6.1 编写 gns3_server.conf
gns3-server 在 Unix 下的配置查找顺序是：当前工作目录的 gns3_server.conf → $HOME/.config/GNS3/2.2/gns3_server.conf → $HOME/.config/GNS3.conf → /etc/gns3/gns3_server.conf → /etc/xdg/GNS3/...。显式用 --config 指定 /etc/gns3/gns3_server.conf 最稳妥，不依赖启动目录。
[Server]
host = 0.0.0.0
port = 3080
config_path = /etc/gns3
projects_path = /var/lib/gns3/projects
images_path = /var/lib/gns3/images
appliances_path = /var/lib/gns3/appliances
symbols_path = /var/lib/gns3/symbols
report_errors = true
local = false
[Qemu]
enable_kvm = false
[Dynamips]
dynamips_path = /usr/bin/dynamips
[VPCS]
vpcs_path = /usr/bin/vpcs
逐项说明：
host = 0.0.0.0：监听所有地址，供远程客户端与 REST API 访问；只允许本机访问时改成127.0.0.1。port = 3080：HTTP 端口，REST API 与 Web UI 都走它。config_path：遗留键，2.2.61 不读取；配置文件位置由启动参数--config决定。projects_path：项目工作目录，每个项目对应一个子目录。images_path/appliances_path/symbols_path：节点系统盘文件、设备模板定义、拓扑图标三类资源的根目录。report_errors = true：崩溃时上报；闭环内网可改false。local = false：非本地模式，允许远程管理；为true时会放开部分不安全接口。[Qemu] enable_kvm = false：本机 KVM 不可用，显式关闭，否则 QEMU 节点启动会直接失败。qemu_path/dynamips_path/vpcs_path：节点后端的可执行文件路径。注意[Qemu]节的qemu_path在 2.2.61 不生效——源码里没有该键的读取点，QEMU 二进制按 PATH 探测；真正指定 QEMU 路径要在创建节点/模板时传qemu_path属性（漏传会报QEMU binary path qemu-system-None is not found in the path）。dynamips_path/vpcs_path则是全局生效的。
💡 技术拓展：QEMU 的硬件加速方式不止 KVM 一种。常见选项对比——
加速方式 原理 适用场景 KVM 利用 CPU 虚拟化扩展（VT-x/AMD-V）直接执行客户机指令 有 /dev/kvm的物理机，性能接近原生TCG 纯软件二进制翻译执行 无硬件虚拟化、嵌套虚拟化受限、跨架构模拟 HVF macOS Hypervisor.framework macOS 客户端本机运行 WHPX Windows Hypervisor Platform Windows 客户端本机运行 本文实测环境无法访问 KVM 模块，
[Qemu]采用 TCG（即enable_kvm = false），性能代价见第八章。
6.2 编写 systemd 单元
用 systemd 托管，避免手动后台进程随会话退出：
[Unit]
Description=GNS3 server 2.2.61
After=network-online.target libvirtd.service
Wants=network-online.target
[Service]
Type=simple
User=root
Group=root
WorkingDirectory=/opt/gns3
ExecStart=/opt/gns3/venv/bin/gns3server --config /etc/gns3/gns3_server.conf --log /var/log/gns3/gns3_server.log
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
写入路径为 /etc/systemd/system/gns3-server.service，要点：
User=root：QEMU 节点需要访问/dev/kvm、创建 TAP 接口与网桥，普通用户容易在权限上翻车；若要用非 root 账号，需usermod -aG libvirt,kvm <用户>并额外配置 capabilities。After=libvirtd.service：NAT 节点与 virbr0 依赖 libvirtd 先就绪。Restart=on-failure：进程异常退出时 5 秒后重启，避免一次崩溃后长时间不可用。WorkingDirectory=/opt/gns3：固定工作目录，避免 gns3-server 优先读取当前目录下的配置文件而覆盖/etc/gns3的设定。
6.3 启用并启动
systemctl daemon-reload
systemctl enable gns3-server
systemctl start gns3-server
Created symlink /etc/systemd/system/multi-user.target.wants/gns3-server.service → /etc/systemd/system/gns3-server.service.
状态检查（输出节选，已省略与判断无关的行）：
systemctl status gns3-server --no-pager
● gns3-server.service - GNS3 server 2.2.61
Loaded: loaded (/etc/systemd/system/gns3-server.service; enabled; vendor preset: enabled)
Active: active (running) since Tue 2026-10-27 13:09:32 UTC; 5s ago
Main PID: 282 (gns3server)
Tasks: 1 (limit: 2932)
Memory: 78.1M
CPU: 518ms
Oct 27 13:09:32 gns3-server systemd[1]: Started GNS3 server 2.2.61.
再用两个短命令复核状态，便于写监控脚本：
systemctl is-enabled gns3-server
systemctl is-active gns3-server
enabled
active
七、安装后验证
7.1 端口与进程
ss -ltnp | grep 3080
LISTEN 0 100 0.0.0.0:3080 0.0.0.0:* users:(("gns3server",pid=282,fd=14))
监听在 0.0.0.0:3080，进程名 gns3server，与配置文件一致。
7.2 REST 版本接口
curl -s http://127.0.0.1:3080/v2/version
{
"local": false,
"version": "2.2.61"
}
version 返回 2.2.61，local 为 false，说明服务端已按非本地模式拉起。
7.3 Web UI 与首页跳转
curl -s -i http://127.0.0.1:3080/ | head -8
HTTP/1.1 302 Found
Content-Type: text/plain; charset=utf-8
Location: /static/web-ui/bundled
Content-Length: 10
Date: Tue, 27 Oct 2026 13:09:46 GMT
Server: Python/3.10 aiohttp/3.13.5
根路径 302 到内置 Web UI，跟随后确认页面真实存在：
curl -s http://127.0.0.1:3080/static/web-ui/bundled | head -5
<!DOCTYPE html><html lang="en"><head>
<meta charset="utf-8">
<title>GNS3 Web UI</title>
<!-- It's important to have base here because of the script below //-->
<base href="/static/web-ui/">
7.4 日志确认
tail -6 /var/log/gns3/gns3_server.log
2026-10-27 13:09:38 INFO compute.py:369 Connecting to compute 'local'
2026-10-27 13:09:38 INFO web_log.py:232 127.0.0.1 [27/Oct/2026:13:09:38 +0000] "GET /v2/compute/capabilities HTTP/1.1" 200 553 "-" "Python/3.10 aiohttp/3.13.5"
2026-10-27 13:09:38 INFO notification_handler.py:50 New client has connected to compute WebSocket
2026-10-27 13:09:38 INFO compute.py:436 Connected to compute 'local' WebSocket 'http://127.0.0.1:3080/v2/compute/notifications/ws'
2026-10-27 13:09:46 INFO web_log.py:232 127.0.0.1 [27/Oct/2026:13:09:46 +0000] "GET / HTTP/1.1" 302 200 "-" "curl/7.81.0"
日志里出现 Connected to compute 'local' 表示 controller 已经与本机 compute 建立连接，这是 2.2 架构里「单机即 controller+compute」的正常表现。
八、KVM 不可用时的降级方案与性能代价
8.1 现象
QEMU 节点启动前，先确认宿主到底能不能用硬件虚拟化：
ls -l /dev/kvm
crw-rw---- 1 root kvm 10, 232 Oct 27 13:09 /dev/kvm
设备节点存在，但这并不代表内核模块可用。直接让 QEMU 走 KVM 加速：
qemu-system-x86_64 -accel kvm -machine pc -display none -nodefaults
Could not access KVM kernel module: No such device
qemu-system-x86_64: -accel kvm: failed to initialize kvm: No such device
这是典型的「节点在、模块不可用」：/dev/kvm 是设备文件，但宿主没有加载/暴露 KVM 内核支持，ioctl 直接失败。查一下 QEMU 支持的加速器：
qemu-system-x86_64 -accel help
Accelerators supported in QEMU binary:
tcg
kvm
8.2 降级配置
在 [Qemu] 段设置 enable_kvm = false（本文 6.1 已配置），QEMU 节点会自动走 -accel tcg 纯软件模拟。用一条最小命令验证 TCG 能跑起来：
time timeout 6 qemu-system-x86_64 -accel tcg -machine pc -m 256 -display none -nodefaults -monitor none
real 0m6.004s
user 0m0.048s
sys 0m0.023s
qemu-system-x86_64: terminating on signal 15 from pid 369 (timeout)
进程按预期被 timeout 终止，说明 TCG 路径可用（该命令只验证加速器初始化，不加载客户机系统）。
8.3 性能代价
TCG 用软件翻译客户机指令，启动与运行都明显慢于 KVM。经验量级是 5–20 倍差距，具体取决于客户机负载与指令密度；本实验环境无法给出精确倍数（缺少可对比的 KVM 基线），这一项列为未闭环项，有 /dev/kvm 的物理机上建议补测。
工程上的取舍：
- 只做拓扑连通性、协议行为验证 → TCG 可接受，但路由器启动要等更久，批量开机应错峰。
- 要跑高负载主机节点、并发多台设备 → 必须上 KVM，或把 compute 迁移到开放
/dev/kvm的物理机。 - 混合部署：controller 留在本机，compute 指到有 KVM 的服务器（compute 注册与连接在配置篇展开），本机只负责编排。
8.4 权限核对
id
getent group kvm libvirt
uid=0(root) gid=0(root) groups=0(root)
kvm:x:108:
libvirt:x:112:
root 直接运行无需额外加组。若改用普通账号（如 gns3），需执行 usermod -aG libvirt,kvm gns3 并重新登录使其生效，否则会出现「能创建节点但启动时报权限拒绝」。libvirtd 状态也要一并确认：
systemctl is-active libvirtd
virsh -c qemu:///system version | head -4
active
Compiled against library: libvirt 8.0.0
Using library: libvirt 8.0.0
Using API: QEMU 8.0.0
Running hypervisor: QEMU 6.2.0
九、常见问题
9.1 3080 端口被占用，服务起不来
ss -ltnp | grep 3080
若输出里已有其他进程，先停掉它，或在 /etc/gns3/gns3_server.conf 改 port，同时同步 systemd 单元与客户端连接地址。改端口后必须 systemctl restart gns3-server 并重新验证 /v2/version。
9.2 PPA 装完发现版本不是 2.2.61
实测 PPA 候选为 2.2.55~jammy2。若已装 PPA 版本，先 apt-get remove --purge -y gns3-server 卸载，再按方案 A/B 安装 2.2.61；两套不要同时跑，避免争抢 3080 端口。
9.3 pip 安装卡在下载主包
现象是 Downloading gns3_server-2.2.61-py3-none-any.whl 长时间无进度。处理方式是换国内软件源：
/opt/gns3/venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple gns3-server==2.2.61
软件源仍不可达时再考虑代理。切勿反复中断重试，pip 会复用本地缓存，换源后通常很快续上。
9.4 服务启动即退出，日志报配置读取失败
日志里出现：
No configuration file could be found or read
这不是致命错误，但意味着服务端用了内置默认值（默认监听 127.0.0.1:3080、路径落在用户目录）。用 --config /etc/gns3/gns3_server.conf 显式指定后重启即可；systemd 单元的 ExecStart 必须带这个参数。
9.5 QEMU 节点启动失败并提示 KVM
报错原文：
KVM acceleration cannot be used (/dev/kvm doesn't exist). It is possible to turn off KVM support in the gns3_server.conf by adding enable_kvm = false to the [Qemu] section.
按第八章关闭 enable_kvm；如果宿主确实有可用 KVM，则检查 /dev/kvm 权限（属组 kvm）与服务运行账号是否在该组。
十、卸载与清理
先停服务再删文件，顺序不能反（服务在跑时删 venv 会留下半死进程）：
systemctl stop gns3-server
systemctl disable gns3-server
rm -f /etc/systemd/system/gns3-server.service
systemctl daemon-reload
rm -rf /opt/gns3 /etc/gns3 /var/lib/gns3 /var/log/gns3
若走的是 PPA 路线，则用：
apt-get remove --purge -y gns3-server
add-apt-repository -y --remove ppa:gns3/ppa
系统依赖（QEMU/libvirt 等）若没有其他用途可一并 apt-get remove --purge，但 libvirt 常被其他虚拟化工具共用，建议保留。
十一、参考链接
- GNS3 官方 Linux 安装文档：https://docs.gns3.com/docs/getting-started/installation/linux/
- gns3-server PyPI 页面：https://pypi.org/project/gns3-server/
- gns3-server 源码仓库：https://github.com/GNS3/gns3-server
- GNS3 官方 PPA：https://launchpad.net/~gns3/+archive/ubuntu/ppa
- 相关篇目：《GNS3 2.2.61 介绍与选型指南》