人员计数

项目地址：YQisme/hik_people_count

基于海康门禁 SDK 的人员进出监控与看板系统。后端采集门禁事件并对外提供 HTTP API，前端 Vue 看板实时展示在场人数、进出记录、报警与异常信息。

门禁设备

效果图

项目结构

├── backend/                 # 后端（C# / .NET）
│   ├── config/              # 本地配置（*.json 不纳入 Git，见 *.example 模板）
│   ├── ACSEventConsole.sln  # 解决方案入口
│   └── GetACSEvent/
│       ├── ACSEventConsole.csproj   # 控制台服务（推荐）
│       ├── GetACSEvent.csproj       # 带界面的 SDK 示例程序
│       └── bin/Debug/net8.0/            # dotnet 编译输出目录
└── frontend/                # 前端看板（Vue 3 + Vite + TypeScript）
    ├── src/
    └── dist/                # 生产构建产物

环境要求

快速开始（开发模式）

1. 启动后端

cd backend/GetACSEvent
dotnet run --project ACSEventConsole.csproj

首次运行前，请从模板复制配置文件并按实际环境修改：

cp backend/config/DeviceConfig.json.example backend/config/DeviceConfig.json
cp backend/config/EmployeeConfig.json.example backend/config/EmployeeConfig.json

启动成功后，后端默认监听 8081 端口。可通过浏览器访问健康检查接口验证：

http://localhost:8081/health

2. 启动前端

新开一个终端：

cd frontend
yarn
yarn dev

浏览器打开 http://localhost:5173 即可查看看板。

Vite 开发服务器会将 /api、/events、/images、/config、/health 等请求代理到 http://localhost:8081，.env.local 中 VITE_API_BASE_URL 留空即可。

3. 生产部署（可选）

# 构建前端静态资源
cd frontend
yarn build

# 预览构建结果
yarn preview

后端保持运行 ACSEventConsole.exe；前端可将 frontend/dist/ 部署到任意静态文件服务器，并通过环境变量指定 API 地址（见下文）。

运行顺序

1. 启动后端 dotnet run --project ACSEventConsole.csproj
2. 启动前端 yarn dev
3. 打开浏览器访问 http://localhost:5173

配置说明

配置文件位于 backend/config/ 目录。修改后需重启后端生效。

首次部署，从模板复制并编辑：

cp backend/config/DeviceConfig.json.example backend/config/DeviceConfig.json
cp backend/config/EmployeeConfig.json.example backend/config/EmployeeConfig.json

DeviceConfig.json 也可通过 Web 接口在线查看/编辑（EmployeeConfig.json 需手动编辑文件后重启）：

• GET /config — 查看当前设备配置
• GET /config/edit — 在线编辑设备配置

DeviceConfig.json

门禁与系统运行参数，顶层分为 config（全局）和 devices（设备列表）。

该文件已加入 .gitignore，不会提交到仓库。含设备密码、MQTT 凭证等敏感信息，请在各环境自行维护。

config — 全局参数

各 MQTT 块均包含对应的 *ClientId 字段，用于区分客户端连接。

devices — 门禁设备

devices 为数组，每项代表一台门禁设备：

配置示例：

{
  "config": {
    "webPort": 8081,
    "limitCount": 500,
    "stayWarningMinutes": 30,
    "recentRecordCount": 10,
    "exitGraceSeconds": 8,
    "capacityWarningRatio": 0.9,
    "mqttEnabled": true,
    "mqttHost": "192.168.0.12",
    "mqttPort": 1883
  },
  "devices": [
    {
      "ip": "192.168.0.164",
      "userName": "admin",
      "password": "your-password",
      "port": 8000,
      "enabled": true,
      "name": "门禁1",
      "deviceName": "测试门禁164",
      "direction": "进",
      "controlDoorNo": 1,
      "doors": []
    }
  ]
}

EmployeeConfig.json

员工信息 JSON 数组，启动时从本地加载，用于将门禁事件中的工号/卡号映射为姓名、部门等展示字段。

该文件已加入 .gitignore，不会提交到仓库。请在各环境自行维护，勿将含真实身份证、手机号等敏感信息的文件推送到 Git。

常用字段

后端会按 employeeId、employeeNo、card_id、name 等字段与刷脸事件关联。门禁设备返回的员工号需与表中 employeeId 或 employeeNo 一致，才能正确显示姓名。

配置示例：

[
  {
    "employeeId": "10001",
    "employeeNo": "10001",
    "name": "张三",
    "card_id": "CARD001",
    "department": "技术部",
    "position": "工程师",
    "status": "在职"
  }
]

可通过 GET /api/employee 查看当前已加载的员工列表。

前端 API 地址

复制环境变量示例文件并按需修改：

cd frontend
cp .env.example .env.local

.env.local 示例：

# 留空则开发模式走 Vite 代理；生产环境可填写完整后端地址
VITE_API_BASE_URL=http://192.168.0.29:8081

直接运行已编译版本（可选）

若无需修改后端代码，可跳过 dotnet run，直接运行已有产物：

cd backend/GetACSEvent/bin/Debug/net8.0
./ACSEventConsole.exe

主要 API 接口

默认服务地址：http://localhost:8081

更详细的接口说明见 backend/GetACSEvent/事件API说明.md。

常见问题

前端页面无数据

• 确认后端 ACSEventConsole.exe 已启动且 /health 可访问
• 确认 DeviceConfig.json 中门禁设备 IP、账号配置正确，设备网络可达
• 开发模式下确认前端运行在 5173 端口（Vite 代理依赖此端口）

端口冲突

• 后端端口：修改 DeviceConfig.json 中 config.webPort
• 前端端口：修改 frontend/vite.config.ts 中 server.port

MQTT 相关功能不可用

• 检查 DeviceConfig.json 的 config 中 MQTT 主机地址与端口
• 若暂不需要 MQTT，可将对应 *MqttEnabled 设为 false

相关文档

• backend/README.md — 后端独立项目说明
• backend/GetACSEvent/事件API说明.md — 事件 API 详细文档
• backend/GetACSEvent/图片服务器使用说明.md — 图片服务说明