Connector Agent 部署

TIP

这是一篇帮助中心文档，重点说明“怎么部署、怎么切换模式、怎么排障”。

适用场景

当连接器需要在客户侧网络、内网系统或边缘主机上运行时，可以使用 Connector Agent 完成：

• 客户侧 Runtime 身份注册
• 配置下发
• 首次注册与 token 轮换
• 本地连接器执行与状态上报

控制面入口

进入 PM7 控制面的 连接器管理 页面，在“客户侧运维”区域完成以下动作：

1. 创建 Agent
2. 绑定该 Agent 负责的连接器
3. 发布配置
4. 获取 agent_id
5. 获取一次性 agent_token
6. 如需首次注册模式，额外生成 bootstrap token

IMPORTANT

如果某个 Agent 暂时不应继续使用，可以在 Agent 卡片中执行“停用 Agent”。停用后，agent_token、bootstrap token、配置发布和回滚都会被阻断。

页面联动

Connector Agent 的创建、启用、停用、凭据轮换都在 连接器管理 页面完成。

部署文档负责说明：

• 哪些环境变量需要准备
• 长驻模式和首次注册模式如何切换
• systemd、docker compose、Kubernetes 的注入示例
• 常见故障如何排查

架构与边界

Connector Agent 默认部署在靠近数据源的位置，例如：

• SAP / 金蝶 所在应用网络段
• Windchill / Teamcenter 所在 PLM 网络段
• 数据库、文件共享、SFTP、私有 REST API 可达的内网主机

Agent 只承担客户侧职责：

• 拉取控制面配置
• 本地运行适配器
• 执行边缘处理
• 写入本地状态
• 批量发送事件到 PM7 云端
• 上报心跳和运行态

PM7 云端承担：

• Agent 注册
• 配置下发
• Token 轮换
• 配置版本发布/回滚
• 事件接收与流程拼接

网络要求

客户侧只需要放通 Agent 到 PM7 的出站 HTTPS：

• /api/v1/connector-agents/register
• /api/v1/connector-agents/me/config
• /api/v1/connector-agents/heartbeat
• 连接器 webhook / ingest 接口

不需要：

• PM7 反向进入客户内网
• 打开入站端口
• VPN 回连

运行模式

oneshot

仅初始化目录并输出路径，不访问云端。

PM7_AGENT_ONESHOT=1

用途：

• 首次验证挂载目录是否正确
• 验证容器镜像或服务模板是否能正常启动

self-check

访问控制面拉取配置，验证当前 Token 与网络连通性。

PM7_AGENT_SELF_CHECK=1
PM7_API_BASE_URL=https://pm7.example.com
PM7_AGENT_TOKEN=...

用途：

• 部署后自检
• Token 轮换后的快速确认
• 网络排障

register

使用 bootstrap token 首次注册 Agent。

PM7_AGENT_REGISTER_MODE=1
PM7_API_BASE_URL=https://pm7.example.com
PM7_AGENT_BOOTSTRAP_TOKEN=...
PM7_AGENT_NAME=pm7-agent-shanghai-plm
PM7_AGENT_PLATFORM=linux

输出：

• agent_id
• 一次性 agent_token

默认长驻模式

这是正式运行模式。Agent 会：

• 周期拉配置
• 同步 connector 集合
• 重放 pending 批次
• 按并发限制运行 connector
• 聚合 heartbeat

必需环境变量：

PM7_API_BASE_URL=https://pm7.example.com
PM7_AGENT_ID=...
PM7_AGENT_TOKEN=...
PM7_AGENT_LOCAL_KEY=...

token 说明

agent_token

• 用于 Agent 正式运行时鉴权
• 由控制面创建 Agent 或轮换 token 时一次性返回
• 页面关闭后不再显示明文

bootstrap token

• 仅用于 register 模式首次接入
• 重新生成后旧值立即失效
• 不能和 agent_token 混用

快速检查清单

在客户侧主机启动前，先确认下面四项：

• 控制面已经创建 Agent
• 连接器已经绑定到该 Agent
• 正式运行模式下已经拿到 agent_token
• 首次注册模式下已经拿到 bootstrap token

环境变量建议

以下变量最常用：

变量名	说明
PM7_API_BASE_URL	PM7 控制面地址
PM7_AGENT_ID	长驻模式使用的 Agent ID
PM7_AGENT_TOKEN	长驻模式使用的正式 token
PM7_AGENT_BOOTSTRAP_TOKEN	首次注册模式使用的 bootstrap token
PM7_AGENT_NAME	首次注册时的 Agent 名称
PM7_AGENT_PLATFORM	首次注册时的运行平台
PM7_AGENT_LOCAL_KEY	本地状态加密密钥
PM7_AGENT_SELF_CHECK	1/true/yes/on 表示自检模式

部署示例

systemd

[Unit]
Description=PM7 Connector Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
EnvironmentFile=/etc/pm7/connector-agent.env
ExecStart=/usr/local/bin/python -m app.connector_agent
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

systemd-env

PM7_API_BASE_URL=https://pm7.example.com
PM7_AGENT_ID=11111111-1111-1111-1111-111111111111
PM7_AGENT_TOKEN=replace-with-agent-token
PM7_AGENT_SELF_CHECK=0
PM7_AGENT_LOCAL_KEY=replace-with-fernet-key
PM7_AGENT_CONFIG_DIR=/var/lib/pm7-agent/config
PM7_AGENT_STATE_DIR=/var/lib/pm7-agent/state
PM7_AGENT_LOG_DIR=/var/log/pm7-agent

docker-compose

services:
  connector-agent:
    image: pm7-connector-agent:local
    env_file:
      - ./connector-agent.env
    volumes:
      - /opt/pm7-agent/config:/var/lib/pm7-agent/config
      - /opt/pm7-agent/state:/var/lib/pm7-agent/state
      - /opt/pm7-agent/logs:/var/log/pm7-agent
    restart: unless-stopped

compose-env

PM7_API_BASE_URL=https://pm7.example.com
PM7_AGENT_ID=11111111-1111-1111-1111-111111111111
PM7_AGENT_TOKEN=replace-with-agent-token
PM7_AGENT_SELF_CHECK=1
PM7_AGENT_LOCAL_KEY=replace-with-fernet-key

kubernetes-secret

apiVersion: v1
kind: Secret
metadata:
  name: pm7-connector-agent-env
type: Opaque
stringData:
  PM7_API_BASE_URL: https://pm7.example.com
  PM7_AGENT_ID: 11111111-1111-1111-1111-111111111111
  PM7_AGENT_TOKEN: replace-with-agent-token
  PM7_AGENT_SELF_CHECK: "1"
  PM7_AGENT_LOCAL_KEY: replace-with-fernet-key

kubernetes-deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: pm7-connector-agent
spec:
  template:
    spec:
      containers:
        - name: connector-agent
          image: pm7-connector-agent:local
          envFrom:
            - secretRef:
                name: pm7-connector-agent-env

推荐部署顺序

1. 先完成连接器配置
2. 在“客户侧运维”中创建 Agent
3. 为 Agent 绑定连接器并发布配置
4. 按目标环境选择长驻模式或首次注册模式
5. 在客户侧主机启动 Runtime
6. 回到控制面确认最近心跳、配置版本和运行连接器数量

排障

看不到 Agent 心跳

优先检查：

• 客户侧主机是否能访问 PM7_API_BASE_URL
• agent_token 或 bootstrap token 是否过期
• 是否已经为该 Agent 发布配置

首次注册失败

优先检查：

• bootstrap token 是否最新生成
• PM7_AGENT_NAME 与 PM7_AGENT_PLATFORM 是否已传入
• 是否错误地把 agent_token 当成 bootstrap token

Agent 已注册但没有运行连接器

优先检查：

• 创建 Agent 时是否绑定了连接器
• 对应连接器是否已启用
• 是否已经执行“发布配置”

相关页面

• 连接器管理
• AI Agent