# 钉钉扫码支持 - 内网穿透方案 ⚠️ 谨慎使用

> ⚠️ **重要安全提示**
>
> cpolar 等第三方内网穿透服务**存在数据合规风险**：
> - 所有签到数据经过第三方服务器
> - 多数公司**明文禁止内网穿透**
> - 员工私自搭建可能承担法律责任
>
> **企业环境强烈推荐自建 HTTPS**：查看 [DEPLOY-HTTPS.md](./DEPLOY-HTTPS.md)
>
> 个人/临时场景可以继续使用本方案。

## 原理

钉钉内置浏览器对 H5 页面有**三重安全限制**：

1. **拒绝 `file://` 协议** → 双击 HTML 打开的本地页面，钉钉直接拒绝
2. **风控内网 IP**（`192.168.x.x`、`10.x.x.x`）→ 扫码后显示"网络不给力 -1004"
3. **强制 HTTPS** → 即使是公网 IP，没 HTTPS 钉钉也不开

**解决方案**：用内网穿透工具把本机的 HTTP 服务，暴露成一个**公网 HTTPS 域名**。

```
钉钉扫码 → 公网 HTTPS 域名 → 内网穿透服务 → 本机 HTTP 服务
```

## 推荐工具：cpolar（国内访问快、免费版够用）

### 1. 注册 cpolar 账号

访问 https://www.cpolar.com/

- 点击「注册」
- 用手机号或邮箱注册（**免费**）
- 登录后进入「仪表盘」

### 2. 下载并安装 cpolar

访问 https://www.cpolar.com/download

- Windows 用户下载 **「cpolar 安装包」**
- 一键安装，安装完会创建一个**桌面快捷方式**

### 3. 验证账号

打开 **「cpolar 网页隧道」** （桌面图标）：

- 首次打开会要求登录
- 登录后会自动保存 token 到本机

### 4. 启动会议签到系统

**先** 启动本机的 HTTP 服务（用之前的 start.bat）：
- 双击 `start.bat` → 选 `1`（本机模式）
- 不要关闭弹出的黑色命令行窗口（那是 HTTP 服务）
- 浏览器自动打开 `http://localhost:8000/host.html`

**确认服务能访问**：
- 浏览器能打开 host.html
- 看到签到二维码

### 5. 用 cpolar 把 8000 端口暴露到公网

**方法 A：用 cpolar 客户端（推荐，零配置）**

打开 cpolar 客户端 → 「隧道管理」 → 「创建隧道」：

| 字段 | 填写 |
|---|---|
| 隧道名称 | `checkin` |
| 协议 | `http` |
| 本地端口 | `8000` |
| 域名类型 | `二级子域名` |
| 子域名前缀 | `mycompany-checkin`（自己取，全网唯一） |
| 地区 | `China` |

点击「创建」。

> 免费版只能使用随机域名或部分保留前缀。**如需固定二级域名需升级**（约 30 元/月，团队建议升级）。

**方法 B：用命令行（更简单）**

打开 PowerShell 或 cmd：

```bash
cpolar http 8000
```

会输出类似：

```
http://xxxxxxx.cpolar.io -> http://localhost:8000
https://xxxxxxx.cpolar.io -> http://localhost:8000
```

复制 **`https://xxxxxxx.cpolar.io`** 这个地址——这就是公网 HTTPS 域名。

### 6. 测试

手机（**不连 WiFi，用 4G/5G**）打开：
```
https://xxxxxxx.cpolar.io/host.html
```

如果能打开，说明穿透成功。

### 7. 钉钉扫码测试

回到浏览器，刷新主持人页：
- 二维码链接应自动变成 `https://xxxxxxx.cpolar.io/checkin.html`（取决于 URL 参数）
- 用钉钉扫描这个二维码
- 钉钉应能正常打开签到页

## 配置启动器自动启动 cpolar

修改 `start.bat` 增加 cpolar 自动启动：

```bat
@echo off
chcp 65001 >nul
title 会议签到系统

cd /d "%~dp0"

echo ========================================
echo        会议签到系统 - 一键启动
echo ========================================
echo.

REM 检测 Python
where python >nul 2>&1
if %errorlevel%==0 (set PY_CMD=python) else (
    where py >nul 2>&1 && (set PY_CMD=py) || (
        echo [错误] 未安装 Python
        pause & exit /b 1
    )
)

REM 检测 cpolar
where cpolar >nul 2>&1
if %errorlevel%==0 (goto :has_cpolar) else (
    echo [警告] 未检测到 cpolar，钉钉扫码将不可用
    echo        下载: https://www.cpolar.com/
    echo.
    set /p USE_CPOLAR=是否继续? (y/n):
    if /i not "%USE_CPOLAR%"=="y" exit /b 1
)

:has_cpolar
REM 启动 HTTP 服务
start "MCI-HTTP" cmd /k "%PY_CMD% -m http.server 8000"
timeout /t 2 /nobreak >nul

REM 启动 cpolar 穿透
if exist "cpolar.exe" (
    start "MCI-cpolar" cmd /k "cpolar http 8000"
) else (
    start "MCI-cpolar" cmd /k "cpolar http 8000"
)

echo.
echo [✓] HTTP 服务已启动
echo [✓] cpolar 穿透已启动
echo.
echo 查看穿透地址：检查 cpolar 窗口的输出
echo.

REM 打开浏览器（用 localhost，先调试）
start "" "http://localhost:8000/host.html?popup=1"

pause
```

## 三种方案对比

| 方案 | 费用 | 钉钉扫码 | 稳定性 | 推荐场景 |
|---|---|---|---|---|
| 本机 HTTP + 不穿透 | 免费 | ❌ 不可 | — | 临时、个人 |
| 本机 HTTP + cpolar | 免费 | ✅ 可 | 中 | 小团队 |
| 升级 cpolar 固定域名 | ~30元/月 | ✅ 可 | 高 | 中大型团队 |
| 公司内网 IIS | 免费 | ❌ 不可 | 高 | 不用钉钉 |
| 阿里云/腾讯云服务器 | ~50元/月 | ✅ 可 | 高 | 大型团队 |

## 替代工具

| 工具 | 网址 | 特点 |
|---|---|---|
| **cpolar** | https://www.cpolar.com/ | 国内、免费版有 HTTPS |
| ngrok | https://ngrok.com/ | 国际版，国内访问慢 |
| frp | https://github.com/fatedier/frp | 自建，需有公网服务器 |
| 花生壳 | https://hsk.oray.com/ | 国产老牌，配置稍复杂 |
| 闪库 | https://www.ipyingshe.com/ | 国产，免费 |

## 进阶：固定公网域名

cpolar 免费版的公网域名**每次重启会变**（随机子域名）。要让域名不变：

1. 升级 cpolar 至基础版（约 ¥30/月）
2. 仪表盘 → 预留域名 → 保留一个你的专属子域名
3. 创建隧道时使用「二级子域名」并填你保留的子域

**这样重启电脑后，钉钉扫码的地址永远不变**。

## 安全提示

### 1. cpolar 暴露的域名是公网可访问的！

- 任何知道这个 URL 的人都能访问你的签到系统
- 建议：**只在会议期间开启 cpolar**，会后关闭
- 签到系统的数据存在浏览器 localStorage 里，相对安全
- 但**不要在签到系统里存放敏感信息**（如未公开的会议主题、参会人手机号等）

### 2. 钉钉扫码后的安全

- 钉钉扫码后会调起钉钉内置浏览器
- 内置浏览器会通过钉钉账号体系识别用户
- 我们的签到系统不收集钉钉账号信息，只用「姓名+工号」

### 3. 公司政策

- 部分公司**禁止内网穿透**（数据外泄风险）
- 部署前**务必确认公司政策**或咨询 IT 部门

## 常见问题

### Q1：cpolar 启动后看不到 https 链接？
A：cpolar 启动需要几秒钟，等待 5-10 秒再看窗口输出。

### Q2：手机用 4G 能打开，但钉钉扫码后还是报错？
A：检查 cpolar 链接是否带 `https://`，钉钉不接受 `http://`。

### Q3：cpolar 免费版够用吗？
A：个人和 10 人以下小团队够用。超过 10 人同时签到或需要稳定地址，升级基础版。

### Q4：公司有公网 IP 服务器，怎么自建？
A：用 frp，需要有公网 IP 的服务器做中转。配置较复杂，不推荐非技术人员使用。

### Q5：有没有不花钱的永久方案？
A：唯一方案是**公司内网 IIS + 内网域名 + HTTPS 证书**。但内网域名**钉钉仍然拒绝**（内网 IP 风控），所以对钉钉扫码没用。

## 推荐组合（按预算）

| 预算 | 方案 |
|---|---|
| **0 元** | 本机 start.bat + cpolar 免费版 + 手机相机/微信扫码 |
| **0 元（只用钉钉）** | 本机 start.bat + cpolar 免费版 + 钉钉扫码 |
| **30 元/月** | cpolar 基础版（固定域名） + 钉钉/微信通用 |
| **50 元/月** | 阿里云/腾讯云学生机 + 自建 HTTPS + 独立域名 |

## 总结

如果你确定要支持钉钉扫码，**cpolar 是最简单的方案**。配置 5 分钟，无需懂技术。

如果只需要支持微信/手机相机扫码（已经能用），**无需任何额外配置**。