4.2 让 Agent 在 Windows 上跑稳：正式构建、配置与断网可用

上一节，我们没有急着安装环境，而是先确认了使用范围、部署主机、主机责任人和网络审批路径。

现在假设部署条件确认单已经写清楚：机房排座系统准备放在一台校内常开的 Windows 电脑上，先给两三位信息科技老师试用。

接下来才轮到真正的部署操作。

不过，这一步也不是把开发电脑上的整个文件夹复制过去，再运行一次 npm run dev。开发时追求修改方便，部署时追求的是配置明确、数据稳定、重启后还能恢复。

先分清开发运行和正式运行

第三章为了方便观察页面变化，主要使用开发服务器。它适合边改边看，但不适合作为长期运行方案。

主线项目的 package.json 中，几条命令承担的任务不同：

项目命令	主要用途	是否适合长期提供服务
npm run dev	开发调试，修改代码后快速刷新	不建议
npm run build	检查项目并生成生产构建结果	这是上线前检查
npm run start	启动已经完成构建的生产服务	本章采用的基本方向

老师不必背下这些命令，但要知道 Agent 不能用“开发服务器已经打开”代替“生产构建已经通过”。

如果生产构建失败，通常说明项目还存在类型、依赖、配置或外部资源问题。不要跳过错误直接把开发服务器当成正式服务。

让 Agent 先做部署主机体检

在部署主机上用 IDE 打开完整项目目录，然后让 Agent 先检查环境，不要立即安装。

请根据当前项目和这台 Windows 主机做一次生产部署检查。

先用中文报告：
1. Node.js、npm、MySQL、端口和项目目录是否满足要求。
2. package.json 中开发、构建和生产启动命令分别是什么。
3. .env.example 中哪些配置必须在部署主机重新设置，报告时隐藏密码和密钥。
4. 准备执行哪些数据库或 Prisma 操作，它们是否会影响现有数据。
5. 项目是否引用在线字体、CDN、远程脚本、图片或接口，断开外网后会影响什么。
6. 建议怎样验证生产构建、生产启动和断网可用。

先给出检查结果和执行计划。未经我确认，不要安装全局软件，不要修改系统设置，
不要迁移或删除数据库，也不要执行构建和启动。

检查结果至少应该覆盖 Node.js、MySQL、项目端口和环境变量。如果 Agent 只检查了 Node.js 版本，可以提醒它继续阅读 prisma/schema.prisma、.env.example 和登录配置。

涉及系统的操作要逐项确认

安装软件、修改系统环境变量、建立数据库、同步数据库结构和开放端口，都可能影响这台电脑的其他用途。让 Agent 先说明操作对象、影响范围和恢复办法，老师确认学校规定后再执行。

不要直接复制 node_modules

有些老师为了省时间，会把开发电脑上的整个项目目录复制到部署主机，其中也包括体积很大的 node_modules。

这样看似省了一次下载，实际容易把旧依赖、缓存和与原电脑相关的文件一起带过去。更稳妥的做法是复制或克隆项目代码，再由 Agent 根据锁文件和当前主机安装依赖。

可以让 Agent 先说明它准备采用 npm install 还是其他安装方式、需要访问哪个镜像源、会生成哪些目录。下载卡住时，继续沿用 3.2 的国内镜像排查方法，不要为了“卡死”反复删除整个项目。

项目目录还要继续遵守 3.7 的 .gitignore 边界：依赖目录、构建产物、日志、.env 和真实数据库不进入 Git。

.env 不是可以公开复制的说明书

主线项目需要通过 .env 连接 MySQL，并配置登录地址、密钥和管理员账号。.env.example 只是模板，不能把示例值原样当成正式配置。

其中几项尤其重要：

配置项	负责什么	老师需要确认什么
DATABASE_URL	告诉项目怎样连接 MySQL	主机、端口、数据库名和账号是否正确
NEXTAUTH_SECRET	保护登录会话	使用随机密钥，不能沿用示例文本
NEXTAUTH_URL	告诉登录系统正式访问地址	不能继续写成本机 localhost 地址
ADMIN_USERNAME	初始管理员账号	不使用容易猜到的默认值
ADMIN_PASSWORD	初始管理员密码	必须更换示例密码并妥善保管

可以要求 Agent 协助生成和检查，但报告中只能显示脱敏结果：

请根据 .env.example 为这台部署主机整理配置方案。

只说明每个配置项的用途、值的来源和检查方法，不要在回复中显示完整密码或密钥。
请检查示例默认账号和密码是否需要更换，并确认 .env 已被 .gitignore 排除。
在我确认访问地址、数据库账号和学校使用范围前，不要创建或覆盖 .env。

如果项目采用“首次登录即创建账号”之类的策略，还要让 Agent 解释当前规则是否会让任何能打开页面的人都创建账号。首次小范围试用至少要知道谁能登录、谁是管理员，不能只换一个密码就当作权限检查已经完成。

数据库操作不能靠猜

热身项目使用过 SQLite，而机房排座主线项目使用的是 MySQL。它的班级、学生、布局和排座结果不会保存在某个随手复制的单文件里。

部署时，Agent 可能建议创建数据库、生成 Prisma 客户端或同步数据库结构。这些操作看起来都是命令，但风险并不相同。

老师可以继续追问：

请逐项解释准备执行的 MySQL 和 Prisma 操作：
1. 它只是读取检查，还是会创建数据库、表或修改结构？
2. 当前数据库里如果已经有数据，会不会被覆盖或删除？
3. 执行成功后怎样用模拟数据验证连接和保存？
4. 如果失败，怎样保留完整错误现场？

先解释，不要执行任何会写入或修改数据库的操作。

首次部署仍然使用模拟班级和模拟名单。涉及已有数据库时，必须先完成备份；正式的备份与恢复演练会放在 4.4，不在这里用真实数据冒险。

由 Agent 分步完成生产构建

主机环境、.env 和数据库方案确认后，再允许 Agent 按计划逐步执行。不要一句话要求“全部安装并上线”，而是分成几个可以判断成功与否的阶段。

1. 确认 Node.js、npm 和 MySQL 状态。
2. 安装当前项目依赖。
3. 准备本机 .env，报告时隐藏敏感值。
4. 生成 Prisma 客户端并完成已确认的数据库准备。
5. 执行生产构建。
6. 构建通过后启动生产服务。

每一步结束后，都让 Agent 报告实际执行内容、结果和下一步风险。出现错误时，把完整日志交给 Agent，只处理当前阶段，不顺手升级无关依赖或重构业务代码。

生产服务启动后，先在部署主机上完成基本验证：登录、打开布局、导入模拟名单、保存排座、刷新页面和打开投屏模式。终端显示“ready”并不等于数据库和登录流程都正常。

学校网络限制，分成安装时和使用时看

校园白名单问题不能只用一句“把 CDN 本地化”概括。先分清两个时间点：

• 安装和构建时：npm 包、在线字体或构建工具可能需要访问外网。
• 老师实际使用时：页面、字体、脚本、图片和接口是否仍会请求校外地址。

主线项目使用了在线字体相关能力。Agent 需要判断字体是在构建阶段下载，还是实际打开页面时仍然访问外网。如果校园网络拦截导致构建失败或页面样式异常，就让 Agent 提出本地字体或系统字体方案，并说明会修改哪些文件。

还可以让它搜索：

• http:// 和 https:// 外部地址。
• CDN 脚本和样式。
• 远程图片、图标和字体。
• 运行时调用的外部接口。

不要要求 Agent 机械替换所有网址。有些地址只是文档链接，有些只在安装时使用。先让它分类，再处理真正影响校园运行的依赖。

断开外网，再做一次完整操作

联网构建完成后，可以在不影响校园其他业务的前提下模拟外网受限环境，例如暂时断开部署主机的外网连接，但保留校内局域网。

然后从浏览器完成下面这些动作：

验收动作	预期结果
打开登录页并登录测试账号	页面和样式完整，登录成功
打开或新建测试布局	数据能够读取和保存
导入模拟学生名单	不依赖校外接口，错误提示正常
完成一次排座并刷新	刷新后数据仍然存在
打开投屏和只读分享	页面元素、字体和图标完整
重启生产服务后再次访问	项目能够重新启动，测试数据仍在

如果某一步失败，记录页面地址、操作时间、完整现象、浏览器错误和服务日志，再让 Agent 只分析这一项。不要因为一个字体失败就重装数据库，也不要因为登录失败就关闭整个防火墙。

让 Agent 留下一份部署说明

构建和断网验证通过后，让 Agent 在项目中生成一份 部署说明.md。其中只记录操作方法和脱敏后的配置名称，不记录真实密码。

请根据这次实际部署结果生成一份中文的 部署说明.md，内容包括：
1. 部署主机需要的环境和版本。
2. 项目目录、生产构建、启动、停止和状态检查方法。
3. 使用的端口和正式访问地址。
4. 必需环境变量的名称和用途，不写真实密码、账号或密钥。
5. MySQL 数据库所在主机和数据库名称，不写密码。
6. 已完成的断网验收项目。
7. 当前已知限制和需要学校信息中心配合的事项。

先展示准备写入的内容，等我确认后再创建文件。

这份说明会成为后面排错、重启和交接的依据。确认内容没有密钥和真实学生数据后，再按照 3.7 的流程让 Agent 检查差异并提交 Git。

这一次的成功标准

本篇不是以“执行完多少条命令”结束，而是以下结果都能被老师亲自验证：

flowchart LR
  A[Agent 检查主机] --> B[老师确认配置与数据库影响]
  B --> C[Agent 完成生产构建]
  C --> D[本机核心流程验收]
  D --> E[断网环境再次验收]
  E --> F[生成部署说明并 Git 存档]

现在，排座系统已经在部署主机上以生产方式跑起来了。但同一台电脑能打开，还不能证明办公室和机房都能使用。

下一篇，我们从部署主机开始，一层一层走到同办公室电脑和机房电脑，用真实浏览器操作完成内网小范围试用。

封面