端口占用本质是“地址被锁住”，非程序故障；muse spark 1.3 默认监听8000（web）、8001（api）、8002（健康检查），冲突时日志必现“address already in use”；需用lsof/netstat查pid，针对性kill或改端口。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
部署 Muse 智能体时遇到端口占用，本质不是“程序起不来”，而是“地址被锁住了”。它不挑系统、不认框架，只认端口是否空闲。只要监听端口已被占，服务就卡在启动阶段，日志里大概率出现 Address already in use 或 bind: address already in use —— 这是明确信号，别绕弯子查模型或 API Key。
先确认 Muse 默认监听哪些端口
Muse Spark 1.3 默认使用以下端口（可配置）：
-
Web UI 界面：默认 8000（可通过
--port或PORT环境变量修改） - API 服务（OpenAI 兼容接口）：默认 8001
- 内部健康检查/心跳端口：部分部署模式下会额外启用 8002（非公开暴露，但需本地可用）
这些端口若与本地已运行的进程（如另一个 Muse 实例、FastAPI 服务、Vue 开发服务器、甚至某些 IDE 的调试代理）重叠，就会触发冲突。尤其在开发调试阶段，多个终端窗口反复启停，极易残留僵尸进程。
快速定位谁占了端口
别靠猜，用命令直击进程：
-
Linux/macOS：
sudo lsof -i :8000或sudo netstat -tulnp | grep ':8000' -
Windows：
netstat -ano | findstr :8000，再用tasklist | findstr <pid></pid>查进程名
重点关注 PID 和 COMMAND/映像名称。常见“嫌疑人”包括：python（未退出的 Muse）、node（前端 dev server）、java（旧版服务）、Docker（容器映射占了宿主机端口）。
三类典型场景及对应解法
场景一：上次 Muse 没关干净
最常见。Ctrl+C 中断后进程仍在后台跑。直接杀掉：
-
kill -9 <pid></pid>（Linux/macOS） -
taskkill /F /PID <pid></pid>（Windows）
场景二：Docker 容器映射冲突
比如 docker-compose.yml 里把 Muse 的 8000 映射到宿主机 8000，但宿主机已有服务占着——此时不能只杀进程，得改映射：
- 将
ports: ["8000:8000"]改为ports: ["8080:8000"]，然后docker-compose down && docker-compose up -d - 确保
container_port（容器内）不变，只动宿主机侧端口
场景三：想共存多个 Muse 实例
比如一个跑 RAG 测试，一个跑流程编排。不建议硬抢同一端口，应主动隔离：
- 启动第一个：
python -m muse --port 8000 - 启动第二个：
python -m muse --port 8003 --api-port 8004（Muse Spark 1.3 支持独立指定 API 端口） - 配合环境变量更稳妥：
PORT=8005 MUSE_API_PORT=8006 python -m muse
预防比抢救更重要
低成本部署中，端口是稀缺资源。建议从一开始就建立轻量级管理习惯：
- 部署前运行一次
lsof -i :8000-8010扫描常用端口段，避开活跃区 - 在项目根目录放一个
ports.md，记录本项目所有端口用途（含依赖服务如 Milvus 默认 19530） - 用
systemd（Linux）或pm2（Node.js 环境）托管 Muse 进程，避免手动启停遗漏 - CI/CD 脚本中加入端口预检步骤，失败则自动换端口并通知
