端口为什么是它 端口选择的取舍很多人第一次看 chayuan-desktop 桌面单机版的网络配置都会留意到一件事sidecar 默认监听 62581 这个奇怪的端口。这一篇把这个看似随意的数字背后的考虑讲一下。免费开源的AI软件 选端口这件事远没看上去那么随意。先看常用端口的占用情况。8080、8000、3000、5000 这些是 Web 开发里高频出现的端口几乎所有人电脑上某个时刻都有一个进程占着。如果 sidecar 抢了这种端口跟用户其他开发服务冲突的概率非常高。另一类常用端口是 11434Ollama、5173Vite dev、4200Angular dev、9000PHP-FPM同样冲突高发。低频端口范围。IANA 把端口分三段0-1023 是知名端口HTTP、SSH、FTP 这些1024-49151 是注册端口一些服务在这里有备案49152-65535 是动态端口或私有端口。chayuan-desktop 选了 62581 落在私有端口段避开知名服务的占用。具体数字 62581 是怎么选的。有几个候选条件一是不能跟主流开发工具冲突二是要好记一点不然每次填 base URL 太痛苦三是不要跟 chayuan 这个名字撞避免被误解。62581 这个数被选中的原因之一是它在动态端口范围里没被任何知名工具占用且数字组合相对好记六二五八一。为什么固定一个端口而不是随机端口。chayuan-desktop 的固定端口设计有具体考虑。第一个考虑是 chayuan-wps WPS AI 插件 默认连这个端口加载项配置文件里写死了 http://127.0.0.1:62581用户不需要每次开 chayuan-desktop 都重新告诉加载项端口号。第二个考虑是 OpenAI 兼容路由。/openai/v1/* 路径让用户用 OpenAI 官方 SDK 直接连本机后端base URL 设为 http://127.0.0.1:62581/openai/v1固定端口让这个 URL 可以写在脚本里反复用。第三个考虑是 系统集成。各种自动化工具、IDE 插件、命令行工具想接 chayuan-desktop 都需要一个稳定的后端地址。端口被占的处置。固定端口最大的问题是被别的进程抢占。chayuan-desktop 启动时会先尝试绑定 62581如果失败会做几件事第一扫描占用方进程看是不是上次没退干净的 chayuan-server 残留是的话尝试杀掉旧进程后重试第二如果是别的进程占用弹窗告知用户让用户选 强制接管 或 换备用端口第三备用端口策略默认走 62582-62590 这一段按顺序尝试。备用端口模式下 chayuan-wps 加载项会失效因为加载项写死了 62581。这是固定端口设计的代价。如果你长期遇到端口冲突建议查清楚冲突方并解决冲突源而不是依赖备用端口。监听地址 127.0.0.1。这个选择比端口号更重要。chayuan-desktop sidecar 默认绑 127.0.0.1loopback不绑 0.0.0.0所有接口。意味着只有本机进程能连 sidecar外部网络访问不了。这是 本地离线知识库 的安全底线之一。强制单机模式下 sidecar 不响应任何非 loopback 请求避免数据出域。什么场景需要绑 0.0.0.0。多人共享一台后端的场景。但是这种用法已经偏离单机版的初衷如果你需要共享后端应该装多用户版chayuan-server 完整服务单机版不开这个口子。防火墙交互。Windows 上 chayuan-desktop 安装时会请求防火墙规则允许本应用的入站连接。这个对话框默认勾私有网络公共网络不勾。即使勾了 0.0.0.0 监听公共网络上其他机器仍然连不到。macOS 和 Linux 上的防火墙交互各有差异但 loopback 监听都不需要专门配置。端口数字之外的几件事。一是 SSE 流式响应跟普通 HTTP 共用同一端口没有单独的 WebSocket 端口二是文件上传走同一端口但用 multipart 协议三是 OpenAI 兼容路由的 /openai/v1/* 跟自家的 /api/v1/* 在同一端口下并存两套路由前缀分流。国产化支持下的特别注意。某些政企内网会监控所有进程的本地端口监听要求所有端口走预审批。这种环境下需要把 chayuan-desktop 的端口号备案进 IT 系统避免被 EDR 拦截。62581 在这种场景下可能要换成 IT 指定的某个端口对应改加载项配置。总结一句话62581 是一个 不太可能跟别人冲突 加 容易固定下来 加 单机版安全 的端口。它不是最优解但是个稳定可用的解。