From f1b496df49f036d9090bb47fcfbb9a02a06b5513 Mon Sep 17 00:00:00 2001
From: YueGuobin <yueguobin@outlook.com>
Date: Thu, 5 Mar 2026 23:39:59 +0800
Subject: [PATCH] docs: add troubleshooting guide for force kill residual
 processes

Add comprehensive documentation for troubleshooting issues caused by using `kill -9` on gns3server processes. The guide explains the root cause where SIGKILL prevents proper cleanup of child processes like dynamips and vpcs, leading to port conflicts and resource allocation errors when restarting. It provides multiple solutions including manual process cleanup, proper shutdown procedures, and preventive measures with example scripts. This documentation helps users resolve common issues with Dynamips VM creation failures, undefined project_id errors, and TCP port warnings.
---
 .../force-kill-residual-processes.md          | 150 ++++++++++++++++++
 1 file changed, 150 insertions(+)
 create mode 100644 docs/gns3-copilot/troubleshooting/force-kill-residual-processes.md

diff --git a/docs/gns3-copilot/troubleshooting/force-kill-residual-processes.md b/docs/gns3-copilot/troubleshooting/force-kill-residual-processes.md
new file mode 100644
index 000000000..17c43b59b
--- /dev/null
+++ b/docs/gns3-copilot/troubleshooting/force-kill-residual-processes.md
@@ -0,0 +1,150 @@
+# Force Kill (kill -9) 导致残留进程问题
+
+## 问题描述
+
+当使用 `kill -9` 强制关闭 gns3server 进程后，重新启动 gns3server 会出现以下错误：
+
+### 1. Dynamips VM 创建失败
+```
+ERROR gns3server.api.routes.compute:133 Compute node error: Dynamips error when running command 'vm create "R1" 1 c7200
+': unable to create VM instance 'R1'
+```
+
+### 2. project_id 为 "undefined" 的验证错误
+```
+ERROR gns3server.api.server:208 Request validation error in /v3/projects/undefined/nodes/{node_id} (PUT):
+1 validation error:
+  {'type': 'uuid_parsing', 'loc': ('path', 'project_id'), 'msg': 'Input should be a valid UUID, invalid character: expected an optional prefix of `urn:uuid:` followed by [0-9a-fA-F-], found `u` at 1', 'input': 'undefined', ...}
+```
+
+### 3. TCP 端口仍在使用的警告
+```
+WARNING gns3server.compute.project:355 Project d672144c-4de9-4a97-a23d-307ddc3ab9b1 has TCP ports still in use: {5001}
+```
+
+## 根本原因
+
+使用 `kill -9` 强制终止 gns3server 进序时，gns3server 没有机会正确清理其启动的子进程，导致以下残留进程仍在运行：
+
+- **Dynamips hypervisor 进程** (dynamips)
+- **VPCS 虚拟 PC 进程** (vpcs)
+- **Docker 容器**（虽然在日志中显示被移除，但可能有些状态未清理）
+- **其他模拟器进程**
+
+这些残留进程会：
+1. 占用相同的端口号和资源 ID
+2. 保持旧的 socket 连接
+3. 导致新启动的 gns3server 无法重新分配相同资源
+
+## 解决方案
+
+### 方法 1：手动清理残留进程（推荐）
+
+在强制关闭 gns3server 后，查找并清理残留进程：
+
+```bash
+# 查找 dynamips 进程
+ps aux | grep dynamips
+
+# 查找 vpcs 进程
+ps aux | grep vpcs
+
+# 终止残留进程
+killall dynamips
+killall vpcs
+```
+
+### 方法 2：使用 pkill 清理相关进程
+
+```bash
+# 清理所有 GNS3 相关进程
+pkill -9 dynamips
+pkill -9 vpcs
+pkill -6 ubridge
+```
+
+### 方法 3：重启前检查
+
+在重新启动 gns3server 之前，确保没有残留进程：
+
+```bash
+# 检查是否有残留的 GNS3 进程
+ps aux | grep -E "(dynamips|vpcs|ubridge|gns3)" | grep -v grep
+```
+
+## 预防措施
+
+### 1. 使用正确的关闭方法
+
+优先使用以下方法关闭 gns3server，而不是 `kill -9`：
+
+```bash
+# 如果使用 systemd
+sudo systemctl stop gns3server
+
+# 如果直接运行
+# 按 Ctrl+C 或使用正常的 kill 信号
+kill <gns3server-pid>
+```
+
+### 2. 使用 SIGTERM 而不是 SIGKILL
+
+```bash
+# 先尝试正常终止（允许进程清理）
+kill -15 <gns3server-pid>
+
+# 等待几秒，如果进程仍在运行，再使用 kill -9
+sleep 3
+if ps -p <gns3server-pid> > /dev/null; then
+    kill -9 <gns3server-pid>
+fi
+```
+
+### 3. 实现自动清理脚本
+
+可以创建一个启动脚本来检查并清理残留进程：
+
+```bash
+#!/bin/bash
+# cleanup_before_start.sh
+
+# 检查并清理残留的 dynamips 进程
+if pgrep -f dynamips > /dev/null; then
+    echo "发现残留的 dynamips 进程，正在清理..."
+    killall -9 dynamips
+fi
+
+# 检查并清理残留的 vpcs 进程
+if pgrep -f vpcs > /dev/null; then
+    echo "发现残留的 vpcs 进程，正在清理..."
+    killall -9 vpcs
+fi
+
+# 等待端口释放
+sleep 1
+
+# 启动 gns3server
+gns3server
+```
+
+## 技术细节
+
+### 为什么 kill -9 会导致这个问题？
+
+1. **SIGKILL 信号无法被捕获**：进程无法捕获或忽略 SIGKILL 信号，因此没有机会执行清理代码
+2. **子进程成为孤儿进程**：父进程被强制终止后，子进程被 init/PID 1 接管，但它们不知道父进程已死
+3. **资源未释放**：socket、端口、文件锁等资源没有被正确释放
+4. **状态不一致**：gns3server 的内部状态（如端口分配、ID 分配）被清除，但实际资源仍被占用
+
+### 涉及的代码位置
+
+- **Dynamips 进程管理**：`gns3server/compute/dynamips/`
+- **端口分配和跟踪**：`gns3server/compute/project.py:355`
+- **节点更新 API**：`gns3server/api/routes/controller/nodes.py:230`
+
+## 相关问题
+
+- [ ] 考虑在 gns3server 启动时自动检测并清理残留进程
+- [ ] 添加进程健康检查机制
+- [ ] 实现更健壮的端口和 ID 重用逻辑
+- [ ] 添加残留进程检测和警告