智叟云集系统：便携部署、MAC 授权与交付排障
理解软件激活、设备控制权限和客户交付之间的关系。
一、便携交付解决什么问题
研发环境往往依赖固定的 Python 路径、虚拟环境和本机工具目录。如果直接把启动脚本交给客户，换一个解压位置就可能找不到解释器或依赖。便携交付的目标是让程序按自身所在目录定位运行环境、采集代码与设备工具，使“解压后启动”不再依赖开发者电脑上的文件布局。
当前 Windows 64 位便携版已经包含运行环境、界面组件、ADB 连接工具及实验性代理依赖。客户完整解压到可写目录后，通过启动文件进入程序，不需要编辑 Python 路径。目录可以整体移动，但不能只复制启动文件；结果、配置与授权文件需要落盘，因此只读目录和压缩软件内部预览不适合作为运行位置。
已经完成的验证包括：换到另一个含中文和空格的目录后启动窗口、定位包内运行环境、运行 ADB 和代理组件，以及无证书时阻止采集。这说明包内路径可迁移，但不等于已经验证所有客户电脑的防护软件、网络环境和云手机连接条件。
二、启动前必须通过三层检查
| 检查层 | 解决的问题 | 不能替代什么 |
|---|---|---|
| 软件授权 | 当前电脑是否允许使用本产品，是否在有效期内 | 不能替代云手机连接权限 |
| 设备连接授权 | 当前电脑是否能通过 ADB 控制目标云手机 | 不能替代 AI 应用账号登录 |
| 应用登录与可用性 | 目标平台是否允许提交问题与分享 | 不能保证软件授权永不过期 |
固定云手机地址只确定连接目标，并没有把设备控制权授予每台客户电脑。授权码验证成功后，如果 ADB 返回 unauthorized，说明设备尚未接受当前电脑的连接身份；此时应处理设备授权，而不是重新签发软件授权码，也不是反复提交问题。
设备侧可能需要确认调试授权，也可能通过云平台提供的管理方式配置连接公钥。具体方式取决于云平台和设备配置。客户电脑的连接密钥不应混入通用客户端包，开发者的已授权私钥也不应为了“开箱即用”分发给所有客户。
三、MAC 授权码如何工作
为了降低交付成本，当前授权流程使用“客户提供 MAC 地址、管理员生成授权码、客户粘贴激活”的方式。授权码携带产品标识、绑定地址、生效时间、到期时间和授权编号，并附带数字签名。它不是一个可以随意修改日期的配置字符串，客户端必须先验证签名才能接受其中的内容。
管理端使用签发私钥生成签名，客户端只携带验证公钥。两者职责不同：公钥用于验证授权是否由相应签发方产生，不具备签发能力；私钥一旦泄露，持有者就可能生成可被该客户端接受的授权。因此交付给客户的是授权码或证书文件，签发私钥始终保存在管理端。
首次启动没有有效授权时，客户端显示可读取的本机 MAC，并允许粘贴授权码。验证通过后保存本地授权，后续启动及任务开始前继续检查。对于已经激活的客户，续期可以在窗口中输入新授权码，不必重新安装整个程序。
当前授权绑定允许匹配本机可读取的网卡地址之一。电脑有多块网卡时，应选用稳定且实际存在的地址；更换网卡、使用变化的网卡地址或系统环境改变，可能导致绑定不匹配。管理员需要核对变更原因后重新签发，而不是让客户任意修改已签名内容。
四、授权管理端如何组织业务
| 功能 | 管理员操作 | 设计目的 |
|---|---|---|
| 新签发 | 填写客户、MAC 和有效天数 | 使客户与设备授权一一可追溯 |
| 复制授权码 | 签发后复制发送给客户 | 减少文件传递和路径操作 |
| 续期 | 选择原记录并输入延长天数 | 生成新证书，保留历史记录 |
| 查询 | 按客户、机器标识或授权编号搜索 | 定位授权归属与到期时间 |
| 导出 | 生成证书、公钥与说明文件 | 兼容文件交付或归档场景 |
| 旧证书导入 | 验证签名后导入已有记录 | 集中管理此前签发的有效证书 |
续期需要明确计算规则：未到期授权从原到期时间延长；已到期授权从当前签发时刻延长。每次续期生成新的授权编号，并保留与原记录的关联。新证书签发成功不意味着客户已经安装，管理端记录只能证明签发行为，不能离线确认客户实际使用的是哪一张证书。
管理端使用本地记录库保存客户信息、备注、证书和历史关联。客户资料与私钥都属于管理侧资产，不能连同客户端包一起发布。备份应覆盖记录库与原签发私钥；私钥丢失后直接换一把新钥匙，会导致原客户端公钥无法验证新的签名，需要另行安排信任更新。
五、离线授权的能力与限制
离线授权的优点是不用在每次运行时访问授权服务器，部署简单，网络不稳定时也能完成软件身份验证。但它不能实现即时远程撤销；管理员在本地修改记录，并不会让已经发出的证书自动失效。若业务要求点击“停用”后及时生效，需要在线授权检查、可控的离线宽限期以及相应服务端设计。
MAC 地址也不是不可伪造的硬件身份证。具有系统管理能力的人可能修改网卡地址；本地时间可以被调整；源码调试版还可能被修改校验逻辑。因此当前方式适合便捷交付与基础使用管理，不能作为强防复制保证。更高要求需要结合编译发布、代码完整性保护、在线授权与可信时间来源综合设计。
六、部署排障与交付验收
出现“点击开始后立即结束”时，优先检查授权、ADB 连接、文件写入与运行环境。出现 unauthorized 应引导客户完成云手机连接授权；出现应用登录页则需要在手机上处理账号状态；任务运行数分钟后失败，应查看最后阶段，而不是只根据耗时猜测网络原因。
错误必须以用户可理解的方式显示，同时保留原始诊断信息。当前连接提示修正版会把设备未授权直接展示为失败，避免“本批次结束”覆盖错误。客户可以将错误内容交给维护人员，而不必先理解 ADB 的全部技术细节。
交付验收建议依次进行：不同目录解压启动、首次激活、错误 MAC 拒绝、到期证书拒绝、云手机连接授权、单平台完整采集、多平台串行执行、失败信息可见、退出后结果仍可读取。先确认这一闭环，再评估多设备扩容；不能用“窗口能打开”替代真实采集验收。
对于当前固定设备版本，客户不需要填写地址，但仍然控制同一个目标设备。不同电脑不能依靠各自的本地锁实现全局互斥。若要给多名客户同时使用，应在后端集中调度设备，或者为每个客户隔离分配设备，避免多个操作端抢占同一手机。