# TCP、UDP 和 API 拉取开关说明

接入开关都配置在 `syslog-serve` 服务中。修改开关不会删除任务、凭据、checkpoint 或历史日志。

## 1. 两个全局开关

| 环境变量 | 控制内容 | `true` | `false` |
| --- | --- | --- | --- |
| `SYSLOG_SERVER_ENABLED` | 网络监听 | 同时打开 TCP 和 UDP Syslog 监听 | 同时关闭 TCP 和 UDP Syslog 监听 |
| `DEVICE_API_ENABLED` | 设备 API 拉取调度器 | 允许调度已启用的 API 任务 | 停止调度所有 API 拉取任务 |

当前版本的 TCP 和 UDP 共用 `SYSLOG_SERVER_ENABLED`，不能通过两个独立环境变量分别打开或关闭。

`SYSLOG_SERVER_ENABLED` 与 `DEVICE_API_ENABLED` 互不排斥，可以同时打开，也可以只打开其中一种。

## 2. 常用配置组合

| 使用方式 | `SYSLOG_SERVER_ENABLED` | `DEVICE_API_ENABLED` |
| --- | --- | --- |
| 只接收 TCP/UDP 推送 | `true` | `false` |
| 只使用 API 拉取 | `false` | `true` |
| TCP/UDP 和 API 同时使用 | `true` | `true` |
| 暂停所有日志接入 | `false` | `false` |

例如，只使用 API 拉取：

```yaml
services:
  syslog-serve:
    environment:
      - SYSLOG_SERVER_ENABLED=false
      - DEVICE_API_ENABLED=true
```

例如，同时使用设备推送和 API 拉取：

```yaml
services:
  syslog-serve:
    environment:
      - SYSLOG_SERVER_ENABLED=true
      - DEVICE_API_ENABLED=true
```

## 3. 修改后如何生效

环境变量在 `syslog-serve` 启动时读取。修改 Compose 文件后，需要重新创建容器：

```bash
docker compose -f <Compose文件路径> up -d --force-recreate syslog-serve
```

如果 Compose 中的服务名不是 `syslog-serve`，请换成现场实际服务名。

只执行下面的命令不能加载刚修改的 Compose 环境变量：

```bash
docker restart syslog-serve-dm
```

`docker restart` 只重启原容器，仍会使用创建该容器时保存的旧环境变量。

## 4. API 拉取有两层开关

API 拉取必须同时满足：

1. 全局开关 `DEVICE_API_ENABLED=true`；
2. 具体任务的 `enabled=true`。

因此，把全局开关改成 `true` 不会自动恢复已经暂停的任务。任务仍需通过管理接口恢复。

查询任务当前版本：

```bash
export SYSLOG_SERVE_BASE_URL=http://127.0.0.1:8189/syslogserve

curl -sS \
  "${SYSLOG_SERVE_BASE_URL}/api/api-pull-tasks/<taskId>"
```

响应中的 `configVersion` 是任务当前版本。恢复任务：

```bash
curl -sS -X POST \
  "${SYSLOG_SERVE_BASE_URL}/api/api-pull-tasks/<taskId>/resume" \
  -H 'Content-Type: application/json' \
  --data-binary '{"configVersion":<当前版本>}'
```

暂停任务：

```bash
curl -sS -X POST \
  "${SYSLOG_SERVE_BASE_URL}/api/api-pull-tasks/<taskId>/pause" \
  -H 'Content-Type: application/json' \
  --data-binary '{"configVersion":<当前版本>}'
```

每次恢复或暂停成功后，`configVersion` 都会增加。再次操作前要重新查询任务，不能一直使用旧版本号。

## 5. 检查配置是否生效

先查看容器实际使用的环境变量：

```bash
docker inspect syslog-serve-dm \
  --format '{{range .Config.Env}}{{println .}}{{end}}' \
  | grep -E '^(SYSLOG_SERVER_ENABLED|DEVICE_API_ENABLED)='
```

再查看启动日志：

```bash
docker logs --since 5m syslog-serve-dm 2>&1 \
  | grep -E 'TCP Syslog server started|UDP Syslog server started|Both TCP and UDP|设备 API 拉取调度器配置'
```

判断方法：

- 出现 `TCP Syslog server started` 和 `UDP Syslog server started`，表示网络监听已打开；
- 没有 TCP/UDP 启动记录，并且容器环境中 `SYSLOG_SERVER_ENABLED=false`，表示网络监听已关闭；
- 出现 `设备 API 拉取调度器配置: enabled=true`，表示 API 全局开关已打开；
- 出现 `设备 API 拉取调度器配置: enabled=false`，表示 API 全局开关已关闭。

最后还要查询具体 API 任务：

```bash
curl -sS \
  "${SYSLOG_SERVE_BASE_URL}/api/api-pull-tasks/<taskId>/runtime"
```

响应中的 `enabled=true` 表示该任务已启用；`committedWindowEnd` 持续向后变化，才表示任务正在正常推进。

## 6. 端口配置注意事项

当 `SYSLOG_SERVER_ENABLED=true` 时，Compose 还需要发布 TCP 和 UDP 端口，例如：

```yaml
ports:
  - "514:514/tcp"
  - "514:514/udp"
```

端口映射和程序开关是两件事：

- 只有端口映射、但 `SYSLOG_SERVER_ENABLED=false`，程序不会监听 TCP/UDP；
- `SYSLOG_SERVER_ENABLED=true`、但没有正确映射或开放端口，容器外设备仍无法连接；
- 只使用 API 拉取时，可以保留端口映射，但建议同时从 Compose 和防火墙中关闭不需要的入口。