---
name: edge-local-dev-services
description: edge_collector 本地开发与联调服务管理规范。用于在本机或远程开发主机启动、检查、停止 edge/cloud 前后端开发服务和依赖服务，包含 collector、configurator、cloud_server、React/Vite 前端、PostgreSQL、TDengine、Mosquitto、端口占用和日志验证。
---

# edge_collector 本地开发服务

## 适用场景

- 本机启动边缘侧或云平台开发环境。
- 前端页面需要 dev server 联调。
- 后端接口需要本地验证。
- E2E 前需要确认依赖服务。
- 端口冲突、服务没起来、接口连接失败。

## 先读配置

不要假设服务和端口，优先读取：

- `docs/project-overview.md`
- `cloud_server/config/server_config.json`
- `configurator/config/`
- `frontend/*/package.json`
- `package.sh`
- `deploy_cloud.sh`
- `scripts/install_all.sh`
- systemd service 安装脚本

## 常见服务

- 边缘：`collector`、`configurator`、`edge` systemd 服务。
- 云端：`cloud_server`、`cloud-server` systemd 服务。
- 前端：`frontend/config_app`、`frontend/cloud_app`。
- 依赖：PostgreSQL、TDengine、Mosquitto。
- 独立 agent：frpc agent、port forward agent、4G/WiFi 相关脚本。

## 检查流程

1. 查看端口占用：

```bash
ss -lntp
```

2. 查看服务状态：

```bash
systemctl status edge --no-pager
systemctl status cloud-server --no-pager
```

3. 查看最近日志：

```bash
journalctl -u edge --since "10 min ago" --no-pager
journalctl -u cloud-server --since "10 min ago" --no-pager
```

4. 验证接口：

```bash
curl -s http://127.0.0.1/api/status
curl -s http://127.0.0.1:8081/api/health
```

## 前端开发

进入对应目录后：

```bash
npm install
npm run dev
npm run build
```

如果 Node 环境在 97/ARM64 主机异常，优先参考 `scripts/set_env/install_nvm_npm.sh` 和本地 nvm 离线安装规则。

## 禁止事项

- 不要直接连接生产库做写操作。
- 不要随意 kill 非本次启动的进程。
- 不要删除用户已有容器、数据库或运行配置。
- 不要把本地端口和临时密码写死进代码。
- 不要每次同步后都执行 `install_all.sh`，除非用户明确要求。

## 输出

最终说明：

- 启动或检查了哪些服务。
- 使用了哪些端口。
- 哪些接口验证通过。
- 日志里是否有错误。
- 如何停止本次启动的临时服务。