配置项与运维自省

本文列出当前工程的全部运行时配置项与只读查询端点，用于部署、排障和「现在到底是哪个配置在生效」这类问题。

一、配置从哪里读

配置项统一通过 EnvUtils.get 读取，优先级从高到低：

1. EnvUtils 通道（系统属性、环境变量、app.properties 等，具体来源以框架的加载顺序为准）；
2. 服务自带的 browser.properties；
3. 同一份 browser.properties 里的全大写下划线写法，例如 BROWSER_CHROME_PATH 等价于 browser.chrome.path，方便用环境变量覆盖。

代码里不要直接用 System.getenv 读环境变量：那样会绕过上面这套优先级，出现「配了却不生效」。

命令行覆盖示例：

java -Dbrowser.engine=firefox -jar <发行包文件名>.jar
java -Dserver.port=10050 -jar <发行包文件名>.jar

二、配置项清单

浏览器与 profile

窗口与视口

启动、动作与留档

正文与 Markdown 提取（见 17）

读图与 OCR（见 11）

配了 engine=command 但 command 为空时不会装作生效：engineId() 退回 windows，而 get_config 的 ocr.describe 会明说「已退回系统 OCR」。

调用追踪（见 09）

文件暂存（见 09）

配方与脚本

以上共 38 个运行时可配项。另有 chromium.revision 属打包期配置（发行版内嵌浏览器的构建编号），运行时不改。

三、只读查询端点

除唯一的控制端点外，服务还开了三个只读端点，方便脚本与浏览器直接打开：

另外两个非 /playwright/ 前缀的路由：

get_config 的返回结构

{"data":{
  "engine":"chromium",
  "configuredType":"auto",
  "typeChoices":["auto","chromium","chrome","edge","firefox"],
  "profileDir":{"resolved":"<这次真正会用的 profile 绝对路径>","forType":"chrome","perPort":true,
    "configured":null,"cdpConfigured":null,"note":"..."},
  "upload":{"dir":"<暂存目录>","enabled":true,"maxBytes":"67108864"},
  "jsDir":"<execute_js 脚本目录>",
  "trace":{"dir":"<追踪目录>","enabled":true,"redact":true},
  "launchTimeoutMs":60000,
  "action":{"timeoutMs":5000,"jsFallback":true,"mouseFallback":true},
  "workDir":"<服务工作目录>",
  "tasks":0,
  "commands":["start","close","shutdown","..."]
}}

响应里还有 java 与 playwright 两个运行时与依赖版本字段，部署时可用于核对环境，本文不列举具体版本。

profileDir.configured 与 cdpConfigured 是显式配置值（没配就是空），resolved 才是这次真正用的目录，forType 说明它是按哪个浏览器类型解析出来的 —— 排查「配置看着对、登录态却没了」时看 resolved，它与 start 回执里的 data.browser.profileDir 是同一个值。注意 browser.type=chrome 时 resolved 是那条 CDP 路径的目录，不是 shared-<端口>（见 05 第三节）。

四、维护类方法

五、启动与停止

# 开发态
cd playwright-server
mvn spring-boot:run

# 发行版
java -jar <发行包文件名>.jar

# Windows 上后台启动 / 干净停止（推荐）
scripts\run\start-server.cmd -Port 10049 -Engine chromium
scripts\run\stop-server.cmd -Port 10049

启动脚本会等健康检查通过，并把实际生效的引擎与 profile 目录打出来。停止脚本先 shutdown（关任务与共享浏览器）再按端口结束整棵进程树。

停服务前先关任务。 浏览器是独立进程：强杀服务不会关掉它启动的浏览器，残留的浏览器会一直占着 profile 目录，下一次 start 会失败 —— 走 CDP 那条路（本机 Chrome / Edge）时报的是「浏览器启动后立即退出（退出码 21）：(Chrome 没有输出)」，原因是新进程把命令行交给已有实例后自己退出、连输出也被那个实例吃掉了（见 27 第八节）；走持久化上下文时则表现为卡到启动超时。已经留下了孤儿时，先结束残留的浏览器进程再重启服务；服务侧也有兜底（清理 profile 里的残留锁标记，并在首次启动失败后重建驱动重试一次）。

另外两点：

• 重启服务是有代价的：关掉最后一个任务时浏览器就退出了，session cookie 型的登录态会随之失效，人工得重新登录一次；持久 cookie 不受影响。所以「顺手重启一下」之前先想清楚有没有正在进行的登录环节。
• 别直接关掉那个后台黑窗口：窗口寿命等于进程寿命，关窗口就是杀进程。要停服务请用停止脚本。

六、安全提示

• 服务没有鉴权。execute_js 能执行任意脚本，/data/** 能读到所有截图与页面文本，POST /playwright/upload 能往服务端磁盘写文件（只能写进暂存目录、文件名会被清洗，但文件内容不限；browser.upload.enabled=false 可关掉这个接口）。
• 示例通过 localhost 访问，但应用配置只明确了端口，不能据此认定服务仅绑定回环地址。部署时检查实际监听地址；对外暴露前增加访问控制，不要把 /data/** 直接放到公网。
• data/、logs/trace/ 与 upload/ 里的文件都不会自动清理，长期运行要自己定期清理（或定期调 cleanup）。
• 追踪日志默认脱敏，但这是尽力而为：按模式认不出来的个人信息（姓名、门牌号）不会被掩掉，交付或共享日志前自己过一眼。详见 09。