# IT智能服务台 — 资源申请清单

> **📌 使用说明（工作流程）**
>
> 本文档是 IT智能服务台 所有资源申请需求的**统一汇总入口**，适用于：
> - 服务器/域名/网络等资源申请
> - 外部系统 API 对接申请（联软、火绒、aTrust、北森 eHR 等）
> - 任何需要向其他团队（运维/安全/网络）申请权限或资源的任务
>
> **工作流程**：
> 1. 新需求直接添加到本文档对应章节（无对应章节则新建）
> 2. **不单独发送企微消息、邮件或工单** — 所有需求集中在此文档跟踪
> 3. 申请完成后在文档中更新状态（✅/🔄/❌）
>
> **负责人**：宋献（IT支持组，负责终端安全，火绒/联软超管）

---

## 一、背景

IT智能服务台（IT Smart Desk）包含两个部署环境，需向运维申请服务器、域名及反向代理资源：

| 环境 | 用途 | 部署位置 | 访问方式 |
|------|------|---------|---------|
| **预生产** | 内网功能验证 | G端服务器 `10.80.0.129` | 公司内网域名 |
| **生产（NAS）** | 企微端实际使用 | 群晖 NAS `192.168.3.200` | Cloudflare Tunnel 公网域名 |

---

## 二、服务器资源

### 2.1 预生产环境 — G端服务器

| 项目 | 信息 |
|------|------|
| **服务器 IP** | `10.80.0.129` |
| **用途** | 预生产验证（内网测试） |
| **服务端口** | `18080`（Docker Nginx 容器暴露端口） |
| **部署方式** | Docker Compose 4容器（postgres + redis + backend + nginx） |
| **部署路径** | `/home/admin/itdesk/` |
| **现有域名** | `it-dataquery.dc.servyou-it.com`（与数据查询平台共用） |
| **状态** | ✅ 已部署运行 |

### 2.2 生产环境 — 群晖 NAS

| 项目 | 信息 |
|------|------|
| **NAS 内网 IP** | `192.168.3.200` |
| **用途** | 生产环境（企微端实际使用） |
| **部署方式** | Docker Compose 5容器（cloudflared + nginx + backend + postgres + redis） |
| **部署路径** | `/volume1/docker/wecom-it-desk` |
| **外网访问** | Cloudflare Tunnel（无需公网 IP、无需端口映射） |
| **状态** | 🔄 部署包已准备，待上线 |

---

## 三、域名资源

| 域名 | 环境 | 用途 | 类型 | 状态 |
|------|------|------|------|------|
| `it-dataquery.dc.servyou-it.com` | 预生产 | G端服务器反代入口（共用现有域名） | 公司内网域名 | ✅ 已有 |
| `itdesk.amanzac.com` | 生产（阶段一测试） | NAS Cloudflare Tunnel 入口 | Cloudflare 托管域名 | ✅ 已配置 |
| `itsupport.servyou.com.cn` | 生产（正式） | 公司备案域名，后续正式环境使用 | 公司备案域名 | 🔄 待申请/配置 |

> **说明**：
> - 预生产环境复用数据查询平台现有域名，新增 `/itdesk/`、`/itagent/`、`/api/`、`/ws/` 路径即可
> - 阶段一测试使用 Cloudflare Tunnel + `itdesk.amanzac.com`，已配置可用
> - 正式上线后将切换至 `itsupport.servyou.com.cn`（公司备案域名），需走域名申请流程

---

## 四、反向代理路由规则

### 4.1 预生产 — G端 Nginx 反代

在现有 `it-dataquery.dc.servyou-it.com` 的 Nginx 配置中，**新增以下 4 条 `location` 规则**，代理到 `10.80.0.129:18080`：

| 路径前缀 | 用途 | 目标 |
|----------|------|------|
| `/itdesk/` | H5 员工端（企微内置浏览器访问） | `http://10.80.0.129:18080/itdesk/` |
| `/itagent/` | 坐席工作台（PC 浏览器访问） | `http://10.80.0.129:18080/itagent/` |
| `/api/` | 后端 API 接口 | `http://10.80.0.129:18080/api/` |
| `/ws/` | WebSocket 长连接（预留） | `http://10.80.0.129:18080/ws/` |

> **⚠️ 重要**：`/` 根路径保持不变，继续代理到现有数据查询平台。

#### 建议 Nginx 配置片段

```nginx
# ==================== IT智能服务台 — 预生产 ====================
# 后端 API
location /api/ {
    proxy_pass http://10.80.0.129:18080/api/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    # 企微回调超时设置
    proxy_read_timeout 60s;
    proxy_connect_timeout 10s;
}

# WebSocket（坐席端实时通知）
location /ws/ {
    proxy_pass http://10.80.0.129:18080/ws/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_read_timeout 3600s;
}

# H5 员工端
location /itdesk/ {
    proxy_pass http://10.80.0.129:18080/itdesk/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

# 坐席工作台
location /itagent/ {
    proxy_pass http://10.80.0.129:18080/itagent/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
```

### 4.2 生产 — NAS Nginx（Docker 内部）

NAS 环境的 Nginx 已内置于 Docker Compose，**无需运维额外配置**。路由规则如下：

| 路径前缀 | 用途 | 目标 |
|----------|------|------|
| `/itdesk/` | H5 员工端 | 容器内静态文件 `/usr/share/nginx/html/itdesk/` |
| `/itagent/` | 坐席工作台 | 容器内静态文件 `/usr/share/nginx/html/itagent/` |
| `/api/` | 后端 API | `http://backend:8000/` |
| `/ws/` | WebSocket | `http://backend:8000`（upgrade） |

> 详细配置见 `nginx/nginx-nas.conf`

---

## 五、网络连通性要求

### 5.1 预生产环境

| 源（发起方） | 目标 | 端口 | 协议 | 用途 |
|-------------|------|------|------|------|
| 数据平台 Nginx 主机 | `10.80.0.129` | `18080` | TCP/HTTP | 反向代理流量 |
| `10.80.0.129` | 企微 API `qyapi.weixin.qq.com` | `443` | TCP/HTTPS | 企微 Token/AccessToken/消息推送 |
| `10.80.0.129` | Dify AI 服务 `yw-dify.dc.servyou-it.com` | `443`（或内网端口） | TCP/HTTPS | AI 对话调用 |

#### 防火墙规则

```
# 入站规则（数据平台主机 → 10.80.0.129）
源: 数据平台主机IP  →  目标: 10.80.0.129:18080  TCP  允许

# 出站规则（10.80.0.129 → 外部）
目标: qyapi.weixin.qq.com:443          TCP  允许  # 企微 API
目标: yw-dify.dc.servyou-it.com:443     TCP  允许  # Dify AI
```

### 5.2 生产环境（NAS）

| 源（发起方） | 目标 | 端口 | 协议 | 用途 |
|-------------|------|------|------|------|
| NAS `192.168.3.200` | Cloudflare Edge | `443` | TCP/HTTPS（出站） | Tunnel 连接 |
| NAS `192.168.3.200` | 企微 API `qyapi.weixin.qq.com` | `443` | TCP/HTTPS（出站） | 企微回调/消息推送 |
| NAS `192.168.3.200` | Dify AI 服务 | `443` | TCP/HTTPS（出站） | AI 对话调用（预留） |
| 办公网络 | NAS `192.168.3.200` | `18080` | TCP/HTTP | 内网调试访问（可选） |

> **说明**：Cloudflare Tunnel 为**出站连接**，NAS 无需开放任何入站端口，安全性最优。

---

## 六、SSL / HTTPS

| 环境 | 方案 | 状态 |
|------|------|------|
| 预生产 | 复用 `it-dataquery.dc.servyou-it.com` 现有证书 | ✅ 无需额外申请 |
| 生产 | Cloudflare Tunnel 自动 HTTPS 终止 | ✅ 无需申请证书 |

---

## 七、验证方式

### 7.1 预生产环境

| 验证地址 | 预期结果 |
|----------|----------|
| `https://it-dataquery.dc.servyou-it.com/itdesk/` | 显示 H5 员工端页面 |
| `https://it-dataquery.dc.servyou-it.com/itagent/` | 显示坐席工作台页面 |
| `https://it-dataquery.dc.servyou-it.com/api/test-ping` | 返回 `{"code":0,"data":"pong"}` |
| `https://it-dataquery.dc.servyou-it.com/` | 保持原样，跳转到数据查询平台 |

### 7.2 生产环境

| 验证地址 | 预期结果 |
|----------|----------|
| `https://itdesk.amanzac.com/itdesk/` | 显示 H5 员工端页面 |
| `https://itdesk.amanzac.com/itagent/` | 显示坐席工作台页面 |
| `https://itdesk.amanzac.com/api/health` | 返回 `{"status":"healthy"}` |
| `http://192.168.3.200:18080/itdesk/` | 内网直连访问（调试用） |

---

## 九、外部系统 API 对接

### 9.1 联软 LV7000 — 终端管理系统

> 申请日期：2026-06-11 ｜ 负责人：宋献（联软超管） ｜ 优先级：P0（核心映射数据源）

#### 项目背景

IT智能服务台核心目标之一是**打通员工↔终端的映射链路**。联软LV7000拥有最准确的员工账号→终端设备映射数据（`strusername`字段），是终端信息集成的**核心数据源**。

#### API 账户（超管自建）

| 项目 | 说明 |
|------|------|
| **所需权限** | 终端设备查询（P0）、用户信息查询（P0）、准入状态查询（P1）、终端操作（P1） |
| **认证模式** | 全启：IP白名单 + 账号密码 + 一次性Token（纵深防御） |
| **所需信息** | 联软超管后台创建 `ApiAccount` + `ApiPassword`，确认内网访问地址（BaseURL） |
| **操作人** | 宋献（联软LV7000超管权限） |

#### 需要开通的 API 端点

**P0 — 核心查询（必须）**

| # | API 端点 | 用途 | 调用频率预估 |
|---|---------|------|------------|
| 1 | `/terminal?act=queryDevByParams` | 按员工账号/IP/MAC查询终端 | 每次会话 ~1次 |
| 2 | `/devallinfoshowwithpaging?act=getDevAllInfo` | 终端详细硬件+软件信息 | 每次会话 ~1次 |
| 3 | `/querydeptuser?act=getUserInfoByAccount` | 按账号查用户信息 | 缓存刷新，低频 |
| 4 | `/querydeptuser?act=getAllOrgInfo` | 组织架构全量同步 | 每日1次 |

**P1 — 操作与状态（建议）**

| # | API 端点 | 用途 | 调用频率预估 |
|---|---------|------|------------|
| 5 | `/access/onlineUser?act=existOnlineUser` | 查询终端在线状态 | 每次会话 ~1次 |
| 6 | `/terminal?act=noticeAgentMsg` | 向终端推送弹窗消息 | 按需，低频 |
| 7 | `/terminal?act=remoteWakeUp` | 远程唤醒终端 | 按需，极低频 |
| 8 | `/software?act=querysoftwarebydev` | 查询终端安装软件 | 缓存刷新，低频 |
| 9 | `/terminalaudit?act=queryClientPatchAuditInfo` | 补丁安装审计 | 缓存刷新，低频 |

> P1中的 `forcedOffline`（强制下线）为高危操作，初期**不申请**，待安全评审后再开通。

#### IP 白名单配置

需将以下服务器IP加入联软白名单：

| 环境 | 服务器 IP | 用途 |
|------|---------|------|
| 预生产 | `10.80.0.129` | 开发调试 + 功能测试 |
| 正式环境 | （待确认） | 生产部署 |

> 正式环境服务器IP待部署时确认后补报。

#### 网络可达性

需确认从以下节点可访问联软系统端口 **30098**：

- `10.80.0.129`（预生产服务器）
- 开发机（公司内网）

#### 需确认信息

| # | 确认事项 | 用途 |
|---|---------|------|
| 1 | 联软LV7000当前版本号 | 确认API文档是否匹配（参考版本：202210SP v1.1） |
| 2 | `strusername` 字段是否为公司的域账号/企微账号 | 确认员工→终端映射的匹配键 |
| 3 | 联软管理的终端数量 | 评估查询性能和缓存策略 |
| 4 | 公司终端安全助手安装率 | 评估映射覆盖率 |
| 5 | 联软系统内网访问地址 | API调用BaseURL |
| 6 | Token有效时长 | 确认缓存刷新策略（文档默认30分钟） |
| 7 | 是否有调用频率限制 | 防止触发限流 |

#### 安全承诺

1. API账户密码仅存储在环境变量中，**绝不**写入代码或版本库
2. Token仅存储在应用内存中，不落盘
3. 高危操作（强制下线等）需二次确认 + 审计日志，仅admin角色可执行
4. 员工敏感信息（邮箱/电话）前端不展示，后端按需过滤
5. 所有API调用记录审计日志，可追溯

#### 对接时间线

| 阶段 | 内容 | 预计时间 |
|------|------|---------|
| 自建 | 超管后台创建API账户 + 配置权限 | 本周 |
| 配置 | IP白名单 + 网络验证 | 账户创建后1天 |
| 验证 | Postman接口测试 | 配置完成后1天 |
| 开发 | 后端集成模块开发 | ~2周 |
| 联调 | 前后端联调 + 测试 | ~1周 |

---

## 十、联系信息

- **申请人**：宋献，IT支持组（税友集团），负责终端安全
- **火绒/联软对接人**：宋献（超管权限，自行创建API账户，受安全团队管理）
- **项目**：IT智能服务台（IT Smart Desk）
- **紧急程度**：预生产反代配置建议 1-2 个工作日内完成；生产环境 NAS 自建，无需运维介入
- **组织架构说明**：
  - IT支持组 = 终端安全负责团队（非独立"终端安全团队"）
  - 火绒企业版、联软LV7000 均以IT支持组名义申请/配置
  - 跨团队资源申请（服务器/域名等）通过本文档统一跟踪