跳到主要内容

服务端口映射

对外开放的只有一个​

在 AI 技术栈中，占用主机 80 / 443 的只有 plantpulse-proxy(nginx) 这一个。 无论是聊天界面、管理控制台，还是各个 API，全部都经由该代理进入。管理控制台的 HTTPS 端口（默认 5960）也由该代理接收 —— 请参阅下文。

应用容器不发布 80 端口

AI Chat Web 仅在容器内部（expose: 8080）开放。对外暴露的入口只有代理一个 —— 将暴露点集中到一处，在那里统一处理防火墙、审计与 TLS。

按主机名分流​

代理依据 Host 头选择后端。因此必须在 DNS 中将下列名称指向代理 IP，才能访问各服务。

后端直接使用容器名 —— 下表中的值即写入 nginx set $upstream 的字符串，在容器内执行 curl 时也使用该名称。

主机后端（容器名:端口）用途
其余全部（默认）plantpulse-copilot-web:8080AI Chat Web —— 聊天界面
admin.*plantpulse-admin-web:8080管理控制台
llm.*plantpulse-litellm:4000LLM 网关（OpenAI 兼容）
rag.*plantpulse-rag-api:7115RAG 检索 API
timeseries.*plantpulse-timeseries-insight-api:8970时序洞察 API
parser.*plantpulse-document-understanding-api:7120文档解析 API
vision.*plantpulse-vision-api:7130视觉 API

默认主机下的路径 —— 仅用一个域名时​

为免再创建子域名，**默认主机（聊天界面一侧）**上同时开放了下列路径。用一个域名和一张证书即可访问网关与 MCP 服务器。

路径后端用途
/mcp/gateway/plantpulse-mcp-gateway-api:7160/mcp/MCP 网关 —— 外部 MCP 客户端接入的地址（网关密钥 ppgw_…）。管理 REST /api/v1 不对外开放
/llm/plantpulse-litellm:4000/LLM 网关（OpenAI 兼容）—— base_url = "https://<호스트>/llm/v1"
/mcp/rag/plantpulse-rag-api:7115/mcp/RAG MCP 服务器
/mcp/timeseries/plantpulse-timeseries-insight-api:8970/mcp/时序洞察 MCP 服务器
/mcp/parser/plantpulse-document-understanding-api:7120/mcp/文档解析 MCP 服务器
/mcp/vision/plantpulse-vision-api:7130/mcp/视觉 MCP 服务器
  • 请连末尾斜杠一并写上。若不带斜杠访问，会自动补成 308（请求体会被保留）。
  • MCP 传输仅支持 Streamable HTTP，不提供 /sse。
  • 认证由后端完成，而非代理。四个 MCP 在没有 X-API-Key: <PI_INBOUND_API_KEY>（或 Bearer）时一律返回 401。/llm/ 使用网关的主密钥或虚拟密钥。
  • 各后端的指标 /metrics 不是新端口，而是同一端口下的路径，同样位于入站密钥之后 （2026.10 重新发布）→ 日志与监控
LiteLLM 管理界面无法通过 /llm/ui 打开

由于转发时会剥离路径前缀，管理界面的资源链接会错位。请通过 llm.* 主机或直接开放的 :4000/ui 打开管理界面。

默认主机本就是外部可达的主机

这些路径可通过公网公开名称直接访问。若 PI_INBOUND_API_KEY 为空，启动前校验会阻止技术栈启动，但 CHANGE_ME_… 占位符能通过该检查。安装完成后务必用 bin/doctor.sh 确认没有遗留的占位符。

copliot 是仓库名，容器名为 copilot

仓库名为 plantpulse-ai-copliot-web（拼写错误被沿用至今），但容器名是 plantpulse-copilot-web。若按仓库拼写执行 docker logs 将找不到容器。

请确认由谁终止 TLS

代理同时监听 443，但在前端另设负载均衡器或反向代理的部署中，TLS 在那里终止，到达代理的是明文。若配置为忽略前端终止，将产生无限重定向。请先确认属于哪种形态。

管理控制台也通过端口开放​

以 IP 访问的内网用户没有主机名，无法在 443 上选中管理控制台。因此自 2026.10 起，管理控制台有两个按端口区分的入口。

地址接收方键（默认值）
http://<AI_SERVER_IP>:5959直连 plantpulse-admin-web:8080（明文）PI_ADMIN_WEB_PORT (5959)
https://<AI_SERVER_IP>:5960代理终止 TLS 后转至 plantpulse-admin-web:8080PI_ADMIN_WEB_TLS_PORT (5960)
  • 两者都开放。明文入口不会被重定向回 HTTPS。
  • HTTPS 证书与 443 使用同一套（代理的证书）。控制台不单独持有证书。
  • 如需更改端口，修改主机 env（/etc/kopens/plantpulse-ai.env）中上述两个键后重新启动。
2026.09 及更早版本的 9080 已取消

旧版本将管理控制台开放在 :9080。2026.10 中改为 5959(HTTP) · 5960(HTTPS)，且控制台容器改为非 root nginx，内部端口也由 80 改为 8080。请一并更新书签与防火墙规则。

代理同样以非 root 运行 —— 外部端口不变，仅内部端口变更​

2026.10 的 plantpulse-proxy 不以 root 运行，而是以 uid 10001、gid 0 运行，在容器内部不开放 1024 以下端口。主机（外部）可见的端口没有变化。

主机（外部）代理内部用途
808080HTTP（明文）
4439443HTTPS —— 聊天界面 · admin.* 等按名称路由
PI_ADMIN_WEB_TLS_PORT (5960)8443管理控制台 HTTPS

防火墙、前端负载均衡器与 DNS 仍按原样面向 80 · 443 · 5960 即可。内部端口由 compose 与代理镜像在同一发布版本中一同变更，因此若仅将代理镜像回退到旧版本，连接会被拒绝 —— 回退时请将整个技术栈统一到同一版本。

证书卷（pp-proxy-certs）如果是在 root 时期创建的，密钥为 root 专属，非 root 代理无法读取。 bin/up.sh · restart.sh · update.sh 会在启动前一次性校正属主 → 服务运维

直接对 LAN 开放的端口​

这些端口不经过代理，直接发布到主机。不是绑定到 127.0.0.1，而是开放在所有网络接口上 —— 请用防火墙阻止从内网之外访问。

端口服务为何开放
80 / 443plantpulse-proxy唯一的用户接入点
4000LiteLLMLLM 网关直连（也可通过 llm.* 访问）
7115RAG API供 MCP 客户端（Claude Desktop 等）直连
8970时序洞察 API供 MCP 客户端直连
5959管理控制台（plantpulse-admin-web）—— HTTP运维人员用。也可通过 admin.* 访问
5960管理控制台 —— HTTPS（由 plantpulse-proxy 接收）运维人员用。证书与 443 相同
7474Neo4j Browser图数据库管理 UI（plantpulse-neo4j —— RAG 知识图谱）
7687Neo4j Bolt图数据库查询协议（同一实例）
Neo4j 有两个 —— 数字主线一侧不开放

自 2026.10 起会额外启动一个数字主线专用 Neo4j（plantpulse-digital-thread-neo4j）。该实例不发布端口 —— 只有 plantpulse-digital-thread-api 在 compose 网络内部连接它。上表中的 7474 · 7687 是原有的 plantpulse-neo4j（LightRAG 的知识图谱）→ 数字主线

4000 上有供人员登录的管理界面

:4000/ui 是 LiteLLM 管理界面，使用 PI_LITELLM_UI_USERNAME · PI_LITELLM_UI_PASSWORD（默认 admin / admin123!）登录。由于该端口对 LAN 开放，请在调试投运时修改密码 → 初始密码变更

需启用 profile 才会启动的服务​

不包含在默认启动中，只有以对应 compose profile 启动时才会运行。

端口服务profile
5000本地镜像仓库registry
LOCAL_REGISTRY_UI_PORT（默认 5080）仓库管理 UIregistry
（不发布 —— 内部 8000）录音转写 vLLM plantpulse-asrmedia
（无网络）录音音频库 plantpulse-asr-audio —— 一次性media

registry 用于在隔离网络中从内部获取镜像 → 隔离网络安装。 media 用于视频 · 语音录制转写。无需手动指定 profile 名称，只需在主机 env 中配置 PI_MEDIA_ENABLED=true 一行即可启用 —— 运维脚本会据此附加 profile → 视频 · 语音采集

Phoenix 会启动，但不对主机开放

Arize Phoenix（追踪 UI · OTLP 采集，6006）默认启动 —— 无需启用 profile。 但自 2026.09 起不再发布主机端口。原因在于 Phoenix 没有认证，而其中保存的是提问与回答的正文（包含工具参数中的设备 id · 标签）。管理控制台的状态检查走容器内部地址，因此不受影响。如诊断需要，可按下文「诊断用端口」临时开放。

2026-07 改版时移除的 Langflow(7860) · Jupyter(3500) 已彻底删除，无法恢复。

诊断用端口 —— PP_DEBUG_PORTS=1​

仅在诊断时，将平时关闭的端口按原样开放（compose/docker-compose.debug.yml 覆盖层）。

cd /opt/kopens/plantpulse-ai-docker
PP_DEBUG_PORTS=1 bin/compose-up.sh
端口服务
9081管理控制台后端（admin-api）
8000 · 8003 · 8004vLLM 生成 · 嵌入 · 重排序
8005录音转写 vLLM（仅在启用 media profile 时）
5001docling
8980时序推理服务器
9400DCGM Exporter
6333Qdrant
6006Phoenix
这些端口没有认证

诊断结束后，请在不带 PP_DEBUG_PORTS 的情况下重新启动以关闭它们。

仅限内部（不发布）​

只能在 compose 网络内通过服务名访问。在主机上用 nc -z 探测无响应是正常现象。

服务内部地址（容器名:端口）作用
AI Chat Webplantpulse-copilot-web:8080聊天界面（代理的默认后端）
管理控制台后端plantpulse-admin-api认证主体。由 plantpulse-admin-web 的 nginx 转发
文档解析 APIplantpulse-document-understanding-api:7120parser.* 的后端
视觉 APIplantpulse-vision-api:7130vision.* 的后端
LightRAGplantpulse-lightrag:9621RAG 引擎。文档管理 WebUI（/webui）
Qdrantplantpulse-qdrant:6333向量数据库
Doclingplantpulse-docling-serve:5001文档转换
vLLM（生成）plantpulse-llm:8000本地 LLM 推理
vLLM（嵌入）plantpulse-emb:8000嵌入
vLLM（重排序）plantpulse-rerank:8000重排序
时序推理plantpulse-timeseries-insight-server:8980洞察模型服务
录音转写 vLLMplantpulse-asr:8000语音 → 文字。仅在 media profile 下启动
DCGM Exporterplantpulse-dcgm:9400GPU 指标
Phoenixplantpulse-phoenix:6006追踪 UI · OTLP 采集（默认启动，不发布）
数字主线 APIplantpulse-digital-thread-api:7140连接器注册表 · 工厂图谱镜像 · 聊天用 thread_ 工具。由管理控制台与 MCP 网关调用
数字主线 Neo4jplantpulse-digital-thread-neo4j:7474工厂图谱镜像存储。仅数字主线 API 连接
工程计算 APIplantpulse-engcalc-api:7150聊天用 eng_ 工具（MCP /mcp/）。仅 MCP 网关调用
MCP 网关plantpulse-mcp-gateway-api:7160汇集平台 · 内置 · 外部 MCP 服务器的单一地址（/mcp/）与管理 REST（/api/v1）。由副驾驶与管理控制台调用。存储为平台 PG pi 的 gw 模式（2026.10 再发布（2026-10-20））
两个旧服务已归档

plantpulse-mcp-server(50000) 与 plantpulse-ontology(8888) 已不再作为独立服务存在。MCP · 本体论工具由平台的 server-web 集成 MCP（/api/v5/mcp，api_key 认证）提供。

从平台借用的服务​

PostgreSQL(5432) · Aster TSDB(9042) · Redis/Valkey(6379) · RustFS(9000/9001) 不由 AI 技术栈启动，而是共用 PlantPulse 平台的安装实例。这些端口的防火墙与账号遵循平台侧的安全设置。

端口状态确认​

整体状态确认​

cd /opt/kopens/plantpulse-ai-docker/bin
./status.sh

health.sh 会一并探测各服务的健康检查端点。容器已启动与实际能响应是两回事，故障排查时请使用此方式。

单个端口确认​

# 특정 포트 리스닝 확인
nc -z 127.0.0.1 <port> && echo "OK" || echo "DOWN"

# 포트 사용 프로세스 확인
ss -tlnp | grep <port>

防火墙需开放的端口​

对象需开放端口
全体用户80 / 443（代理）
运维人员（内网）5959 · 5960 管理控制台，7474 Neo4j Browser
MCP 客户端（内网）7115 RAG，8970 TimeSeries

安装程序（install.sh）在开放防火墙后，会将这些端口中已被本技术栈之外的进程占用的以警告形式输出 —— 若置之不理，首次 bin/up.sh 会在技术栈启动到一半时以 «address already in use» 中断。请释放该端口，或在主机 env 中修改可迁移的三个键（PI_LITELLM_PORT · PI_ADMIN_WEB_PORT · PI_ADMIN_WEB_TLS_PORT）。其余端口在 compose 中是固定的。

其他端口即便在内网也没有开放的理由。数据库端口（5432 · 9042 · 6333 6379 · 7687 · 9000）在任何情况下都不得对外暴露。