# ChatLab 正式上线、打包、联网授权、离线授权操作手册

这份文档按实际销售流程写，不讲太多专业词。你可以把它理解成：

```text
先把授权服务放到你的服务器上
再把桌面软件里的授权地址改成你的服务器地址
然后重新打包安装包
客户安装后输入授权码，就会连你的服务器激活
```

---

## 1. 正式上线前你要准备什么

你需要准备 4 样东西：

```text
1. 一台云服务器
2. 一个域名，比如 https://license.xxx.com
3. 授权后台 license_server
4. 打包好的客户安装包
```

建议你正式卖客户时使用：

```text
默认：联网授权
备用：离线授权
```

联网授权适合大多数客户。  
离线授权只给网络限制很严的客户用。

---

## 2. 修改客户软件里的授权服务器地址

正式上线后，先打开这个文件：

```text
electron-launcher/license-config.json
```

本地测试时通常是：

```json
{
  "licenseServerUrl": "http://127.0.0.1:8787"
}
```

正式上线后改成你的公网授权地址：

```json
{
  "licenseServerUrl": "https://license.你的域名.com"
}
```

例子：

```json
{
  "licenseServerUrl": "https://license.chatlab.cn"
}
```

注意：

```text
不要给客户正式包继续使用 http://127.0.0.1:8787
```

因为 `127.0.0.1` 代表客户自己的电脑。  
客户电脑上没有你的授权服务，就会激活失败。

---

## 3. 修改授权地址后怎么打包

在你自己的开发电脑上打开 PowerShell。

进入项目根目录：

```powershell
cd C:\Users\12138\Desktop\get_wechat_new\用户使用版本\第二版\get_wechat_me
```

推荐使用完整打包命令：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1
```

这个命令会重新打包前端、后端和 Electron 安装包。

打包完成后，正式发给客户的是：

```text
release\ChatLab-Setup-1.0.0.exe
```

如果你只是临时测试 Electron 打包，也可以执行：

```powershell
cd .\electron-launcher
npm.cmd run build
```

临时测试输出一般在：

```text
electron-launcher\dist\ChatLab-Setup-1.0.0.exe
```

但正式发客户，建议用：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1
```

---

## 4. 如果你有代码签名证书

正式商业销售建议做代码签名，否则客户电脑可能提示未知发布者。

有证书时使用：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1 `
  -Sign `
  -CertificateFile "D:\certs\ChatLab-CodeSigning.pfx" `
  -CertificatePassword "证书密码" `
  -PublisherName "你的公司名称" `
  -ForceSign
```

如果暂时没有证书，也可以先用普通打包命令：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1
```

只是客户安装时可能会看到系统提醒。

---

## 5. 部署联网授权服务

下面以 Ubuntu 云服务器为例。

### 5.1 上传授权后台

把本地这个目录上传到服务器：

```text
license_server
```

建议服务器上放到：

```text
/opt/chatlab-license-server
```

服务器上的目录大概是：

```text
/opt/chatlab-license-server
  admin_cli.py
  main.py
  license_core.py
  requirements.txt
  dev_private_key.pem
```

注意：

```text
不要把整个桌面软件项目都发到客户电脑。
license_server 是你自己服务器用的，不发给客户。
```

---

### 5.2 安装运行环境

登录服务器后执行：

```bash
cd /opt/chatlab-license-server
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
```

先手动测试运行：

```bash
python main.py
```

如果看到类似：

```text
Uvicorn running on http://127.0.0.1:8787
```

说明授权服务已经启动。

再测试：

```bash
curl http://127.0.0.1:8787/health
```

正常会返回：

```json
{"ok":true}
```

---

## 6. 绑定域名和 HTTPS

假设你的域名是：

```text
license.你的域名.com
```

先在域名解析后台添加：

```text
类型：A
主机记录：license
记录值：你的服务器公网 IP
```

然后服务器安装 Nginx 和证书工具：

```bash
sudo apt update
sudo apt install nginx certbot python3-certbot-nginx -y
```

开放网页端口：

```bash
sudo ufw allow 80
sudo ufw allow 443
```

申请 HTTPS 证书：

```bash
sudo certbot --nginx -d license.你的域名.com
```

成功后，在浏览器打开：

```text
https://license.你的域名.com/health
```

如果看到：

```json
{"ok":true}
```

说明公网授权服务已经通了。

---

## 7. 让授权服务一直运行

手动执行 `python main.py` 只适合测试。  
正式上线要让它一直在服务器后台运行。

创建服务文件：

```bash
sudo nano /etc/systemd/system/chatlab-license.service
```

写入：

```ini
[Unit]
Description=ChatLab License Server
After=network.target

[Service]
WorkingDirectory=/opt/chatlab-license-server
ExecStart=/opt/chatlab-license-server/.venv/bin/python /opt/chatlab-license-server/main.py
Restart=always
RestartSec=3
Environment=CHATLAB_LICENSE_DB=/opt/chatlab-license-server/license_server.db
Environment=CHATLAB_LICENSE_PRIVATE_KEY_FILE=/opt/chatlab-license-server/dev_private_key.pem
Environment=CHATLAB_LICENSE_ADMIN_TOKEN=请改成一串很长的后台管理密码

[Install]
WantedBy=multi-user.target
```

启动服务：

```bash
sudo systemctl daemon-reload
sudo systemctl enable chatlab-license
sudo systemctl start chatlab-license
```

查看状态：

```bash
sudo systemctl status chatlab-license
```

如果看到 `active` 或 `running`，说明授权服务正在运行。

查看日志：

```bash
sudo journalctl -u chatlab-license -f
```

---

## 8. 正式环境私钥怎么处理

私钥可以理解成：

```text
你的授权盖章工具
```

谁拿到私钥，谁就可以自己生成授权。

所以正式上线要记住：

```text
私钥只放你的服务器
不要发给客户
不要放进安装包
不要上传到公开仓库
不要放到网盘分享
```

如果你换了正式私钥，就必须保证：

```text
服务器用新私钥签授权
客户软件里内置的新公钥能验证这个授权
```

如果私钥和公钥不是一对，客户会看到：

```text
授权签名校验失败
```

简单理解：

```text
服务器负责盖章
客户软件负责验章
两边必须是一套章
```

---

## 9. 联网授权怎么做

联网授权是正式销售最推荐的方式。

### 9.1 你先给客户创建授权码

登录服务器：

```bash
cd /opt/chatlab-license-server
. .venv/bin/activate
```

创建一年授权：

```bash
python admin_cli.py create-license --customer-name "某某公司" --days 365
```

如果是 7 天试用：

```bash
python admin_cli.py create-license --customer-name "某某公司-试用" --days 7
```

它会输出类似：

```json
{
  "customer_id": "cus_xxx",
  "license_id": "lic_xxx",
  "license_key": "CL-2026-XXXX-XXXXXX-XXXXXX",
  "expires_at": "2027-05-18T00:00:00Z"
}
```

你要发给客户的是：

```text
license_key
```

也就是类似：

```text
CL-2026-XXXX-XXXXXX-XXXXXX
```

---

### 9.2 你发给客户两个东西

发给客户：

```text
1. 安装包：ChatLab-Setup-1.0.0.exe
2. 授权码：CL-2026-XXXX-XXXXXX-XXXXXX
```

客户操作：

```text
1. 安装软件
2. 打开软件
3. 输入授权码
4. 点“激活并进入”
5. 软件自动连接你的授权服务器
6. 激活成功后绑定当前电脑
```

客户第一次激活成功后，这个授权默认绑定这台电脑。

---

### 9.3 你给客户的话术

可以直接复制：

```text
您好，这是 ChatLab 安装包和授权码。

安装后打开软件，输入授权码即可在线激活。
首次激活会绑定当前电脑。
如果后续更换电脑，请联系我处理换机。
授权期内包含软件维护、问题修复和基础使用支持。
```

---

## 10. 离线授权怎么做

离线授权只建议作为备用方案。

适合这些情况：

```text
客户公司网络拦截你的授权服务器
客户电脑不能访问外网
客户临时无法联网激活
```

不建议默认给客户一年离线授权。  
建议：

```text
普通离线授权：30 天或 90 天
非常稳定客户：180 天
一年离线授权谨慎使用
```

---

### 10.1 客户先复制离线请求码

客户打开软件后：

```text
1. 点“离线授权”
2. 复制“离线请求码”
3. 发给你
```

离线请求码通常是一长串字符，例如：

```text
eyJsaWNlbnNlX2tleSI6IiIsImRldmljZV9maW5nZXJwcmludF9zaGEyNTYiOi...
```

---

### 10.2 你生成离线授权文件

在服务器或你的授权管理电脑上执行：

```bash
cd /opt/chatlab-license-server
. .venv/bin/activate
```

生成 90 天离线授权：

```bash
python admin_cli.py offline-grant \
  --license-key "CL-2026-XXXX-XXXXXX-XXXXXX" \
  --request-code "客户发来的离线请求码" \
  --days 90 \
  --output customer.chatlab-license
```

如果你在 Windows PowerShell 里执行，可以写成一行：

```powershell
python .\admin_cli.py offline-grant --license-key "CL-2026-XXXX-XXXXXX-XXXXXX" --request-code "客户发来的离线请求码" --days 90 --output customer.chatlab-license
```

注意：

```text
--license-key 后面必须是真实授权码
不能写 CL-...
```

错误写法：

```powershell
--license-key "CL-..."
```

正确写法：

```powershell
--license-key "CL-2026-C6D0-4A9B22-F1B5B7"
```

---

### 10.3 把离线授权内容发给客户

命令成功后，会生成：

```text
customer.chatlab-license
```

打开这个文件，把里面全部内容发给客户。

客户操作：

```text
1. 打开软件
2. 点“离线授权”
3. 把你发的授权内容粘贴进去
4. 点“导入离线授权”
5. 成功后进入系统
```

---

## 11. 联网授权和离线授权怎么选

建议你这样定规则：

```text
默认使用联网授权
客户网络有限制时，再使用离线授权
```

推荐策略：

| 场景 | 用哪种 |
|---|---|
| 普通客户电脑能联网 | 联网授权 |
| 客户需要年费续费 | 联网授权 |
| 客户可能换电脑 | 联网授权 |
| 客户公司限制外网 | 离线授权 |
| 客户临时无法访问授权服务器 | 离线授权 |
| 试用客户 | 联网授权，或短期离线授权 |

---

## 12. 常见错误和处理方法

### 12.1 connect ECONNREFUSED

错误类似：

```text
connect ECONNREFUSED 127.0.0.1:8787
```

意思是：

```text
软件找不到授权服务
```

常见原因：

```text
1. 授权服务没启动
2. 软件里的授权地址还是 127.0.0.1
3. 客户电脑访问不到你的服务器
4. 域名或 HTTPS 没配置好
```

处理：

```text
1. 浏览器打开 https://license.你的域名.com/health
2. 确认返回 {"ok":true}
3. 检查 electron-launcher/license-config.json
4. 修改后重新打包安装包
```

---

### 12.2 授权密钥不存在

错误类似：

```text
KeyError: '授权密钥不存在。'
```

常见原因：

```text
1. 你用了 CL-... 这种占位符
2. 授权码输错
3. 你连的是另一份授权数据库
4. 这个客户授权还没有创建
```

处理：

```text
先创建真实授权码，再生成离线授权。
```

创建授权码：

```bash
python admin_cli.py create-license --customer-name "客户名称" --days 365
```

---

### 12.3 授权签名校验失败

意思是：

```text
客户软件验不过授权文件
```

常见原因：

```text
1. 客户改过授权文件
2. 服务器私钥和客户端公钥不是一对
3. 你换了服务器私钥，但没有重新打包客户端
```

处理：

```text
1. 不要让客户手动改授权文件
2. 确保服务器私钥和客户端公钥匹配
3. 换密钥后重新打包客户安装包
```

---

### 12.4 授权文件不属于当前电脑

意思是：

```text
这个离线授权是给另一台电脑生成的
```

处理：

```text
让客户在当前电脑重新复制离线请求码
你重新生成离线授权文件
```

---

## 13. 你每天真实销售时怎么操作

### 联网授权客户

```text
1. 客户付款或试用
2. 你在服务器创建授权码
3. 你发安装包和授权码
4. 客户安装并输入授权码
5. 软件自动激活并绑定电脑
6. 你记录客户信息和到期时间
```

### 离线授权客户

```text
1. 客户付款或试用
2. 你创建授权码
3. 客户复制离线请求码发给你
4. 你生成 customer.chatlab-license
5. 客户导入离线授权
6. 你记录离线授权到期时间
```

---

## 14. 建议你的客户记录表

你可以建一个 Excel，字段如下：

```text
客户名称
联系人
微信
电话
授权码
授权类型：联网 / 离线
购买日期
到期日期
离线授权到期日期
绑定电脑备注
是否已安装
是否已培训
备注
```

这样续费、换机、售后会清楚很多。

---

## 15. 最推荐的正式流程

最终建议你采用这个流程：

```text
1. 授权服务部署到公网服务器
2. 域名使用 HTTPS
3. electron-launcher/license-config.json 改成公网授权地址
4. 重新打包安装包
5. 普通客户使用联网授权
6. 特殊客户使用离线授权
7. 离线授权尽量给 30 天或 90 天
8. 私钥只放服务器，不发给客户
```

一句话总结：

```text
正式销售用联网授权，离线授权只做备用。
改完授权域名后，用 build-desktop.ps1 重新打包，再把 release 里的安装包发给客户。
```