简介围绕《电子用户许可协议EULA详解》整理的Java版Minecraft服务端开服配置参考包面向需要搭建、调试服务端并理解EULA约束的初学者与服主。包内共9个文件以4个yml服务端配置文件、server.properties属性文件、eula.txt文本及server-icon.png图标为主另含2个zip压缩包整体约6.17MB目录简洁便于按用途查找。已有283人学习说明其对开服基础配置与协议认知具有一定参考价值。内容覆盖EULA的性质、许可范围、使用限制、隐私政策、保修与责任限制、更新升级及终止条款等主题并与实际服务端配置场景相呼应读者可据此梳理EULA在软件使用中的权利义务边界同时对照常见服务端配置文件了解参数分布与文件组织方式为后续深入阅读协议和排查配置问题提供线索。1. 从一段静态文字到可交付制品eula 资源包解决的是什么问题多数团队第一次处理 eula是把一段文字塞进安装器、勾一个我已阅读并同意就算完事。等到私有化交付验收、海外版本发版、或者审计方要一份某年某月某台机器上哪个版本同意了哪份文本的记录时才发现这段文字没有版本号、没有指纹、没有留痕连改过几次都说不清。这份 eula 资源包要解决的就是这件事把用户许可协议从一段静态文字变成一份可版本化、可抽取、可校验、可留痕的工程制品。它适合三类人——做桌面客户端安装包的、做私有化交付的、以及被要求证明你展示过的发布工程师。下面按拆包顺序讲结构、抽取、集成、踩坑、验收。2. 拆开看eula 包里到底有什么、按什么规则组织拿到一个只有文本的资源包最容易犯的错是先读正文。正文是给用户看的工程信息全在结构里。先看清目录职责再确认元数据字段能不能撑住后面所有自动化最后再决定要不要用这份东西替换掉你手里那个license.txt。2.1 目录结构与文件职责资源包的组织思路是源文本与产物分离、内容与元数据分离。源文本按语言分目录存放元数据单独一个 YAML工具脚本只读不写源文本所有生成物统一落到dist/。这套划分的好处是后面接 CI 时边界清晰改文本的人只动texts/改流程的人只动tools/两边不会互相覆盖。路径职责谁改是否进版本库texts/lang/eula.md各语言源文本带条款编号内容维护者是meta/eula.yaml版本、语言清单、指纹、展示策略发布工程师是tools/extract.py条款切分输出结构化 JSON工具维护者是tools/fingerprint.py规范化后计算哈希并回写元数据工具维护者是tools/render.py生成安装器可读的纯文本 / RTF工具维护者是dist/渲染产物、留痕模板构建机否产物目录我一般会把dist/直接写进.gitignore。原因很实际产物带时间戳和指纹一旦提交进来每次构建都会产生无意义的 diffreview 的时候真正的文本改动会被淹没。而且产物是可以从源文本完全重建的没有保存必要。还有一个小约定值得抄走texts/下的语言目录名必须和 BCP 47 的写法对齐比如zh-CN、en-US不要出现cn、zh_CN、chinese这类混写。安装器、客户端、留痕表三处都要用这个字符串做键命名一乱后面回退逻辑就得写一堆别名映射血泪经验。2.2 元数据 schema撑住后续自动化的八个字段元数据是整个资源包的控制面。字段设计的原则是凡是被脚本读写两次以上的信息都必须落到 YAML 里不允许散落在脚本常量里。下面这套字段是够用的最小集字段名可以直接照抄。# meta/eula.yaml id: eula-main # 协议标识多协议场景下用来区分不要用中文 version: 3.2 # 面向用户的版本号出现在标题与留痕里 revision: 7 # 同一 version 内的修订号文本微调时递增 release_date: 2025-03-11 # 发布日只做工程溯源不承载其它含义 languages: # 语言清单顺序即回退优先级 - zh-CN - en-US default_language: zh-CN min_app_version: 1.4.0 # 低于该版本的客户端不得展示本协议 placeholders: # 文本中允许被替换的占位符白名单 - product_name - company_name - contact_mail display: require_scroll: true # 是否必须滚到底才允许勾选 must_accept: true # 是否阻断式不接受即退出 storage: keep_days: 1095 # 留痕保留天数由清理任务读取 fingerprint: algo: sha256 value: # 由 fingerprint.py 回写禁止手填version和revision拆成两个字段是这套 schema 里最值得保留的设计。很多团队只有一个版本号结果文本改了一个错别字就得升大版本用户侧看到协议版本 3.3以为条款变了实际只是标点。拆开之后version表示条款实质变化revision表示文本修订留痕表里两个都存出问题能精确定位到某一次构建。min_app_version容易被忽略但它是版本错配的后悔药。老客户端内置的是 2.x 版协议服务端下发 3.x 的文本如果客户端不判断直接渲染就会出现标题写 3.2、条款还是旧的这种翻车现场。placeholders白名单看着多余实际是防御性设计。文本里出现${company_name}但没在安装器里注入用户会看到一串原始占位符反过来如果允许任意变量替换文本作者随手写个${path}就可能被打包脚本误替换成构建机路径。白名单配合校验脚本两头都堵住。2.3 为什么不用一个纯文本文件了事最直接的替代方案是一个license.txt扔进安装器结束。这套做法的成本优势很明显但它在三个地方会立刻崩掉。第一是定位。审计方问3.2 版第 4 条讲的是什么纯文本没有稳定的条款标识只能靠从头数第几段。而资源包里的源文本用 Markdown 标题做条款编号抽取脚本能直接产出{clause: 4.2, text: ...}这样的结构任何一次查询都能落到确定的锚点。第二是比对。纯文本改了之后人眼 diff 只能看出这段变了看不出这段变了是否影响用户已同意的范围。资源包的做法是按条款生成子指纹条款级指纹不变的部分就不需要重新征求同意这条规则能显著减少发版时的弹窗打扰。第三是多语言。纯文本方案里多语言通常变成license_zh.txt、license_en.txt一堆散文件加一段 if-else。资源包用languages列表加回退优先级缺哪个语言就往下走逻辑收敛在一处。代价也有多了一层抽取和渲染构建时间会多一点文本维护者要遵守编号规范。我的判断是只要你的产品有两个以上语言、或者有私有化交付场景这笔投入就是值的纯内部工具、单语言、不对外分发那确实没必要上这套。3. 文本抽取与结构化把 eula 变成可查询的数据源文本进库之后第一件要做的不是渲染是抽取。抽取的意义在于把给人读的段落转成给程序判断的条款单元后面的版本比对、同意范围计算、留痕明细全依赖这一步的输出。3.1 条款切分脚本与编号规范切分规则必须和文本写法强绑定否则脚本会脆。约定是一级条款用## 4.二级条款用### 4.2正文段落跟在标题后面遇到下一个标题就收口。这个规范足够简单写作者不容易写错正则也好写。# tools/extract.py import json import re import sys from pathlib import Path import yaml # 一级## 4. 标题 二级### 4.1 标题 CLAUSE_RE re.compile(r^(#{2,3})\s(\d(?:\.\d)?)\.?\s(.*)$) def split_clauses(md_text: str): 按标题切分条款返回 [{clause, title, level, body}] clauses, cur [], None for raw in md_text.splitlines(): line raw.rstrip() m CLAUSE_RE.match(line) if m: if cur: clauses.append(cur) hashes, no, title m.groups() cur { clause: no, # 条款编号如 4 / 4.2 level: len(hashes) - 1, # 1一级2二级 title: title.strip(), body: [], } elif cur is not None: cur[body].append(line) if cur: clauses.append(cur) for c in clauses: # 段落合并连续空行折叠为一个避免指纹被空行数量影响 text \n.join(c[body]).strip() c[text] re.sub(r\n{2,}, \n\n, text) del c[body] return clauses def main(lang: str): root Path(__file__).resolve().parent.parent meta yaml.safe_load((root / meta/eula.yaml).read_text(encodingutf-8)) src root / texts / lang / eula.md clauses split_clauses(src.read_text(encodingutf-8)) out { id: meta[id], version: meta[version], revision: meta[revision], language: lang, count: len(clauses), clauses: clauses, } dst root / dist / feula.{lang}.json dst.parent.mkdir(parentsTrue, exist_okTrue) dst.write_text(json.dumps(out, ensure_asciiFalse, indent2), encodingutf-8) print(f[extract] {lang}: {len(clauses)} clauses - {dst}) if __name__ __main__: main(sys.argv[1] if len(sys.argv) 1 else zh-CN)脚本逻辑有三处值得说明。CLAUSE_RE用#{2,3}同时匹配两级标题靠捕获组的井号数量反推层级避免写两条正则后面对不上。段落合并时把连续空行折叠成两个换行是为了让指纹只对内容敏感、对排版不敏感——否则编辑在段落间多敲一个回车整份协议的指纹就变了留痕表里会凭空多出一批文本已变更的记录。输出落在dist/并按语言分文件是为了让渲染脚本和安装器脚本各取所需不用重复解析 Markdown。调用方式是python tools/extract.py zh-CN参数就是语言目录名必须和meta/eula.yaml的languages里某一项完全一致脚本不做大小写容错。这个严格是刻意的容错会导致构建机上能过、本地过不了排查起来很烦。写文本的人要守的规矩只有三条编号连续不跳号标题行只写编号和标题不写正文条款正文里不要出现以##开头的行。第三条最容易被违反有人在条款里贴了一段 Markdown 示例直接把切分打乱抽出来的条款数会莫名其妙变多。3.2 指纹计算整份指纹与条款级指纹指纹有两个粒度。整份指纹用于判断这份文本是否等同于上次发布的那份条款级指纹用于判断用户上次同意过的条款里哪些变了。两个都要缺一不可。# tools/fingerprint.py import hashlib import json import unicodedata from pathlib import Path import yaml ROOT Path(__file__).resolve().parent.parent def normalize(text: str) - str: 归一化去 BOM、统一换行、去行尾空白、压缩连续空格 text text.lstrip(\ufeff) text text.replace(\r\n, \n).replace(\r, \n) text \n.join(line.rstrip() for line in text.split(\n)) text unicodedata.normalize(NFKC, text) # 全角/半角、兼容字符归一 return text.strip() def sha256(text: str) - str: return hashlib.sha256(text.encode(utf-8)).hexdigest() def main(): meta_path ROOT / meta/eula.yaml meta yaml.safe_load(meta_path.read_text(encodingutf-8)) per_lang {} for lang in meta[languages]: raw (ROOT / texts / lang / eula.md).read_text(encodingutf-8) norm normalize(raw) clause_hashes {} data json.loads((ROOT / dist / feula.{lang}.json).read_text(encodingutf-8)) for c in data[clauses]: clause_hashes[c[clause]] sha256(normalize(c[title] \n c[text])) per_lang[lang] {doc: sha256(norm), clauses: clause_hashes} # 整份指纹取默认语言条款指纹按语言分别保存 meta[fingerprint][value] per_lang[meta[default_language]][doc] meta_path.write_text( yaml.safe_dump(meta, allow_unicodeTrue, sort_keysFalse), encodingutf-8 ) (ROOT / dist / fingerprint.json).write_text( json.dumps(per_lang, ensure_asciiFalse, indent2), encodingutf-8 ) print([fingerprint] doc , meta[fingerprint][value][:16], ...) # 与上一版比对输出变更条款清单供发版脚本判断是否需要重新征得同意 prev ROOT / dist / fingerprint.prev.json if prev.exists(): old json.loads(prev.read_text(encodingutf-8)) for lang in meta[languages]: changed [ k for k, v in per_lang[lang][clauses].items() if old.get(lang, {}).get(clauses, {}).get(k) ! v ] if changed: print(f[fingerprint] {lang} changed clauses: {sorted(changed)}) if __name__ __main__: main()normalize里四个动作对应四类真实翻车。去 BOM 是因为 Windows 编辑器保存 UTF-8 时常带 BOMLinux 构建机读到的首字符不同同一条款算出两个哈希。统一换行是因为 Git 的core.autocrlf在不同机器上配置不同同一份文件在两台机器上指纹不一致。去行尾空白是防止编辑器自动 trim。NFKC 归一化处理全角标点与兼容字符中文文本里全角逗号和半角逗号混用极其常见不做归一化指纹每天都在变。clause_hashes用title \n text拼起来算是为了让只改标题不改正文也算变更。条款编号本身不参与哈希这样把一个条款从 4.2 挪到 4.3 不会被判定为内容变更。fingerprint.prev.json的存在是给发版脚本用的变更条款清单为空说明只是排版动了用户不需要重新同意清单非空就得走阻断式重新确认。这个文件由构建流程负责在每次成功后重命名别手工维护。3.3 多语言对齐与回退策略多语言的坑不在翻译在对齐。texts/zh-CN/有 24 条texts/en-US/只有 23 条抽取脚本各自跑完都成功但条款级指纹对不上同意范围计算就会错位。校验放在抽取之后立刻做比对语言间的条款编号集合是否完全一致# tools/check_align.py import json from pathlib import Path import yaml ROOT Path(__file__).resolve().parent.parent meta yaml.safe_load((ROOT / meta/eula.yaml).read_text(encodingutf-8)) sets {} for lang in meta[languages]: data json.loads((ROOT / dist / feula.{lang}.json).read_text(encodingutf-8)) sets[lang] [c[clause] for c in data[clauses]] base_lang meta[default_language] base sets[base_lang] ok True for lang, nums in sets.items(): missing [n for n in base if n not in nums] extra [n for n in nums if n not in base] if missing or extra: ok False print(f[align] {lang}: missing{missing} extra{extra}) print([align] OK if ok else [align] FAILED) raise SystemExit(0 if ok else 1)回退策略写在languages的顺序里取第一个存在的语言取不到就用default_language再取不到直接构建失败——不允许静默降级成空字符串。静默降级的后果是安装器弹出一个空白协议页同意按钮还亮着用户点了也能过这种翻车最难受因为它在测试环境里往往复现不出来。关于机器翻译可以用于内部预览但不能直接进texts/。指纹机制会把机器翻译稿和人工稿一视同仁一旦发了版后面就没法区分哪份是正式文本。常见做法是加一个texts/lang/eula.draft.md的旁路目录抽取脚本默认不读只有显式传--include-draft才处理。4. 装机向导落地同意流程的三处集成点文本准备好之后真正的交付在三个地方安装器、客户端首启、留痕存储。三处的展示口径必须一致否则用户会看到两份措辞不同的协议信任度直接归零。4.1 安装器展示渲染产物与页面挂载安装器普遍对 Markdown 不友好所以要先渲染成纯文本或 RTF。渲染脚本的职责只有两个把占位符替换成实际值把 Markdown 标记压平成安装器能认的格式。# tools/render.py import json import sys from pathlib import Path import yaml ROOT Path(__file__).resolve().parent.parent def render(lang: str, values: dict): meta yaml.safe_load((ROOT / meta/eula.yaml).read_text(encodingutf-8)) data json.loads((ROOT / dist / feula.{lang}.json).read_text(encodingutf-8)) allowed set(meta[placeholders]) unknown set(values) - allowed if unknown: raise SystemExit(fplaceholder not in whitelist: {unknown}) lines [f{meta[id]} version {meta[version]}.{meta[revision]}, ] for c in data[clauses]: indent if c[level] 1 else lines.append(f{indent}{c[clause]}. {c[title]}) body c[text] for k, v in values.items(): body body.replace(${ k }, str(v)) lines.append(body) lines.append() text \n.join(lines) # 校验渲染后不允许残留占位符 if ${ in text: raise SystemExit(unresolved placeholder remains after render) out ROOT / dist / feula.{lang}.txt out.write_text(text, encodingutf-8, newline\r\n) # 安装器按 CRLF 更稳 print(f[render] {lang} - {out} ({len(text)} chars)) if __name__ __main__: render(sys.argv[1], { product_name: sys.argv[2] if len(sys.argv) 2 else 某客户端, company_name: 某公司, contact_mail: supportexample.invalid, })newline\r\n是刻意写的。安装器的许可页控件大多是原生 Windows 控件纯 LF 的文件在部分环境里会显示成一整行用户滚不动require_scroll的判定永远为真谁都没法点下一步。这个坑我在两个项目上各踩过一次。unresolved placeholder那条硬校验别删。文本里出现${contact_mail}而值没传安装器上就会显示原始占位符属于一眼可见的低级事故但偏偏很容易漏因为本地默认值往往填得挺全。NSIS 侧挂载许可页只要两行配合自定义的离开回调记录同意动作!define MUI_PAGE_CUSTOMFUNCTION_LEAVE OnLicenseLeave !insertmacro MUI_PAGE_LICENSE dist\eula.zh-CN.txt Function OnLicenseLeave ; $0 用于拼接留痕行写入安装目录下的 consent.log FileOpen $0 $INSTDIR\consent.log a FileWrite $0 langzh-CN$\r$\n FileWrite $0 version3.2.7$\r$\n FileWrite $0 ts$%DATE% $%TIME%$\r$\n FileClose $0 FunctionEndMUI_PAGE_CUSTOMFUNCTION_LEAVE在用户点下一步离开许可页时触发此时同意单选已被选中是写入留痕的正确时机——放进.onInstSuccess就晚了用户可能中途取消留痕会漏。写入用追加模式a避免重装时覆盖历史记录。路径用$INSTDIR是因为它此时已确定别写$TEMP临时目录会被清理留痕等于没留。4.2 客户端首启弹窗版本比对与阻断安装器只管安装那一刻客户端还得管运行期间协议升级。首启逻辑的判定顺序是读服务端或本地配置的最新版本 → 和用户已同意的版本比对 → 不一致则弹窗 → 必须滚到底才解锁同意按钮 → 不接受则退出。比对用(version, revision)元组不要用字符串比较。字符串比较下3.10 3.9会成立这个坑每年都有人踩。用 Python 写个比对函数就三行def is_newer(local: tuple, remote: tuple) - bool: local/remote 形如 (3, 2, 7)返回 remote 是否比 local 新 return tuple(int(x) for x in remote) tuple(int(x) for x in local)require_scroll的判定不要依赖滚动条位置百分比那个值在字体缩放、高 DPI 下不可靠。稳妥做法是给控件挂一个滚动到末尾事件事件触发后置一个布尔位。高 DPI 场景下滚动条的nPos最大值可能小于nMax所有基于位置的计算都会偏。弹窗关闭后无论同意与否都要落一条记录拒绝也是记录因为拒绝次数多了说明文本措辞有问题这是个有用的产品信号。4.3 留痕存储表结构与保留策略留痕表建议单独一个 SQLite 文件不要塞进业务库。理由是保留期不同业务库有备份和清理策略协议留痕的保留期由storage.keep_days控制混在一起会让清理逻辑互相打架。CREATE TABLE IF NOT EXISTS consent ( id INTEGER PRIMARY KEY AUTOINCREMENT, eula_id TEXT NOT NULL, version TEXT NOT NULL, revision INTEGER NOT NULL, lang TEXT NOT NULL, fingerprint TEXT NOT NULL, -- 当时的整份指纹 action TEXT NOT NULL, -- accept / decline channel TEXT NOT NULL, -- installer / first_run / upgrade machine_hash TEXT NOT NULL, -- 机器标识的哈希不存原始值 created_at TEXT NOT NULL ); CREATE INDEX IF NOT EXISTS idx_consent_ver ON consent(eula_id, version, revision); CREATE INDEX IF NOT EXISTS idx_consent_ts ON consent(created_at);fingerprint必须存。只存版本号的话同一版本号下的多次修订就无法区分事后无法证明用户同意的到底是哪份文本。这个字段是整个留痕表的价值所在。machine_hash存哈希不存原始机器码是出于数据最小化考虑。同一台机器多次同意会产生多行这是正常的别做去重合并——重装、换语言、协议升级都应该各留一条。保留策略由清理任务读取keep_days执行删除前先做一次归档导出CSV 或 JSON Lines别直接DELETE。见过直接在安装器里跑DELETE ... WHERE created_at ...的写法一旦日期格式解析出问题整表清空那真是没有后悔药。5. 避坑与排查五个能把发版卡住的真实问题下面五条都是我在拆这类资源包时真遇到过的按现象 → 原因 → 解决记。前三个偏文本与编码后两个偏集成与留痕。5.1 文本层的三个坑坑一同样的文件两台机器指纹不一致。现象是构建机上跑fingerprint.py得到的哈希和本地不同CI 因此判定文本变更触发了一次不必要的重新同意。 原因有两层一是 Git 在 Windows 上默认core.autocrlftrue检出时把 LF 换成了 CRLF二是某个编辑器在保存时加了 BOM。两者都会改变字节流。 解决办法是把归一化前置到所有读文件的地方normalize()里那四步一个都不能省同时在仓库根加.gitattributes对texts/**声明-text让 Git 不要做换行转换。做完这两步同一份内容在任何机器上算出的指纹都一致。坑二条款数突然变多。现象是抽取脚本输出的count从 24 变成 27check_align.py报某几个条款缺失。 原因是有编辑在条款正文里贴了一段以##开头的示例文本切分正则把它当成了新条款把原来的一条切成了三段。 解决办法是短期在编辑规范里加一条正文中禁止以井号开头长期在抽取脚本里加个断言相邻两个条款编号必须连续跳号就报错退出。我一般还会让extract.py输出一条告警列出所有一级条款编号肉眼扫一遍就知道有没有异常。坑三全角半角混用导致频繁误报变更。现象是没人改内容但fingerprint.json里的条款指纹每隔几天就变一次。 原因是不同人用不同输入法中文逗号和英文逗号、全角括号和半角括号混着来甚至同一个词有时候是全角空格分隔。 解决办法就是unicodedata.normalize(NFKC, text)它会把全角 ASCII 统一成半角、把兼容字符归一。注意 NFKC 会改动部分特殊字符的形态如果文本里有需要保持原样的符号要在归一化前做白名单保护。5.2 集成与留痕的两个坑坑四静默安装直接跳过了许可页。现象是批量部署的机器上留痕表一条记录都没有验收方认为未展示协议。 原因是安装器用了/S静默模式MUI_PAGE_LICENSE页面被跳过OnLicenseLeave根本不触发。 解决办法是在静默分支里显式补一条记录把channel标成installer_silent并在部署文档里写明静默安装视为已接受由部署方承担责任。代码上不要试图在静默模式下弹窗那会把自动化部署卡死。坑五升级后协议变了但用户没被重新询问。现象是服务端下发了 3.3 版文本客户端启动后界面显示的仍是 3.2 版用户也不会被要求重新同意。 原因有两个常见版本一是比对用了字符串比较3.10 3.9判断为假二是客户端把已同意版本缓存在注册表里升级安装包时把整个注册表键覆盖了缓存被重置成默认值 0.0反而变成未同意但 UI 又读的是安装目录里的旧文本。 解决办法是比对一律走整型元组缓存键带上eula_id前缀避免被同名键覆盖升级流程里加一步读旧缓存 → 迁移到新键 → 删旧键别直接删。6. 验收与进阶把 eula 纳入 CI 门禁到这一步文本、脚本、安装器集成都有了剩下的问题是怎么保证下次发版不退化。我的习惯是让构建流水线在打包之前先跑一遍校验任何一个检查失败就中断构建不允许先发出去再补。校验脚本写成纯 bash不依赖额外运行时放在tools/ci_check.sh#!/usr/bin/env bash set -euo pipefail LANG_DEFAULTzh-CN echo [ci] 1/6 抽取条款 python tools/extract.py $LANG_DEFAULT echo [ci] 2/6 多语言对齐 python tools/check_align.py echo [ci] 3/6 计算指纹 python tools/fingerprint.py echo [ci] 4/6 渲染安装器文本 python tools/render.py $LANG_DEFAULT 某客户端 echo [ci] 5/6 检查渲染产物无占位符残留 if grep -q \${ dist/eula.$LANG_DEFAULT.txt; then echo [ci] FAIL: unresolved placeholder; exit 1 fi echo [ci] 6/6 检查产物非空且条款数达标 test -s dist/eula.$LANG_DEFAULT.json python - PY import json, sys data json.load(open(dist/eula.zh-CN.json, encodingutf-8)) if data[count] 10: print([ci] FAIL: clause count too low:, data[count]); sys.exit(1) print([ci] clause count , data[count]) PY echo [ci] ALL PASSEDset -euo pipefail是必须的少了pipefail中间某个 python 命令失败会被管道吞掉脚本照样输出 PASSED。第 5 步用grep -q \${做兜底检查因为渲染脚本内部的校验万一被改坏了这一步能独立拦住。第 6 步的条款数下限用 10 是个经验值——不是精确断言而是防止抽取脚本读错了文件这种低级错误把空结果当成成功。这个下限每次协议大改时都要复核一遍别让它变成一个永远为真的摆设。配合 CI还需要一份版本升级的回归清单。这份清单我通常会写成表格贴在发布流程文档里每次动协议文本就照着走一遍触发条件必须执行的动作判定依据仅修正错别字递增revision不弹窗条款级指纹全部未变条款实质变化递增version阻断式重新同意至少一个条款指纹变化新增语言补languages列表并跑对齐检查check_align.py通过客户端大版本升级复核min_app_version老客户端不展示新文本留痕清理策略调整先导出归档再删归档文件行数与表内一致有一点值得单独说min_app_version这个字段在真实发版里经常被忘掉结果服务端配了新版协议一批还在用旧客户端的机器启动后取到新文本UI 又不会渲染新增的条款编号用户看到的是缺号的协议观感极差。我后来把这个字段接进了客户端的启动自检本地版本低于min_app_version就不拉取远端文本只用内置版本并把这条判定写进启动日志。最后提一个进阶玩法——把条款级指纹接进差异通知。发版前跑一次比对如果变更条款清单非空就自动把变更的条款编号和标题整理成一段摘要附在发布单里。审核的人不用打开完整协议只看这几条就能判断要不要重新走一遍确认流程。这一步做完协议文本才算真正从一段话变成了一个有状态、可追溯的工程对象。从那以后我每次接新的安装包项目第一件事就是把texts/和meta/两棵树立起来先跑通extract → fingerprint → render这条链再动安装器脚本——顺序反过来后面必然要返工。希望帮到你。本文还有配套的精品资源点击获取
简介围绕《电子用户许可协议EULA详解》整理的Java版Minecraft服务端开服配置参考包面向需要搭建、调试服务端并理解EULA约束的初学者与服主。包内共9个文件以4个yml服务端配置文件、server.properties属性文件、eula.txt文本及server-icon.png图标为主另含2个zip压缩包整体约6.17MB目录简洁便于按用途查找。已有283人学习说明其对开服基础配置与协议认知具有一定参考价值。内容覆盖EULA的性质、许可范围、使用限制、隐私政策、保修与责任限制、更新升级及终止条款等主题并与实际服务端配置场景相呼应读者可据此梳理EULA在软件使用中的权利义务边界同时对照常见服务端配置文件了解参数分布与文件组织方式为后续深入阅读协议和排查配置问题提供线索。1. 从一段静态文字到可交付制品eula 资源包解决的是什么问题多数团队第一次处理 eula是把一段文字塞进安装器、勾一个我已阅读并同意就算完事。等到私有化交付验收、海外版本发版、或者审计方要一份某年某月某台机器上哪个版本同意了哪份文本的记录时才发现这段文字没有版本号、没有指纹、没有留痕连改过几次都说不清。这份 eula 资源包要解决的就是这件事把用户许可协议从一段静态文字变成一份可版本化、可抽取、可校验、可留痕的工程制品。它适合三类人——做桌面客户端安装包的、做私有化交付的、以及被要求证明你展示过的发布工程师。下面按拆包顺序讲结构、抽取、集成、踩坑、验收。2. 拆开看eula 包里到底有什么、按什么规则组织拿到一个只有文本的资源包最容易犯的错是先读正文。正文是给用户看的工程信息全在结构里。先看清目录职责再确认元数据字段能不能撑住后面所有自动化最后再决定要不要用这份东西替换掉你手里那个license.txt。2.1 目录结构与文件职责资源包的组织思路是源文本与产物分离、内容与元数据分离。源文本按语言分目录存放元数据单独一个 YAML工具脚本只读不写源文本所有生成物统一落到dist/。这套划分的好处是后面接 CI 时边界清晰改文本的人只动texts/改流程的人只动tools/两边不会互相覆盖。路径职责谁改是否进版本库texts/lang/eula.md各语言源文本带条款编号内容维护者是meta/eula.yaml版本、语言清单、指纹、展示策略发布工程师是tools/extract.py条款切分输出结构化 JSON工具维护者是tools/fingerprint.py规范化后计算哈希并回写元数据工具维护者是tools/render.py生成安装器可读的纯文本 / RTF工具维护者是dist/渲染产物、留痕模板构建机否产物目录我一般会把dist/直接写进.gitignore。原因很实际产物带时间戳和指纹一旦提交进来每次构建都会产生无意义的 diffreview 的时候真正的文本改动会被淹没。而且产物是可以从源文本完全重建的没有保存必要。还有一个小约定值得抄走texts/下的语言目录名必须和 BCP 47 的写法对齐比如zh-CN、en-US不要出现cn、zh_CN、chinese这类混写。安装器、客户端、留痕表三处都要用这个字符串做键命名一乱后面回退逻辑就得写一堆别名映射血泪经验。2.2 元数据 schema撑住后续自动化的八个字段元数据是整个资源包的控制面。字段设计的原则是凡是被脚本读写两次以上的信息都必须落到 YAML 里不允许散落在脚本常量里。下面这套字段是够用的最小集字段名可以直接照抄。# meta/eula.yaml id: eula-main # 协议标识多协议场景下用来区分不要用中文 version: 3.2 # 面向用户的版本号出现在标题与留痕里 revision: 7 # 同一 version 内的修订号文本微调时递增 release_date: 2025-03-11 # 发布日只做工程溯源不承载其它含义 languages: # 语言清单顺序即回退优先级 - zh-CN - en-US default_language: zh-CN min_app_version: 1.4.0 # 低于该版本的客户端不得展示本协议 placeholders: # 文本中允许被替换的占位符白名单 - product_name - company_name - contact_mail display: require_scroll: true # 是否必须滚到底才允许勾选 must_accept: true # 是否阻断式不接受即退出 storage: keep_days: 1095 # 留痕保留天数由清理任务读取 fingerprint: algo: sha256 value: # 由 fingerprint.py 回写禁止手填version和revision拆成两个字段是这套 schema 里最值得保留的设计。很多团队只有一个版本号结果文本改了一个错别字就得升大版本用户侧看到协议版本 3.3以为条款变了实际只是标点。拆开之后version表示条款实质变化revision表示文本修订留痕表里两个都存出问题能精确定位到某一次构建。min_app_version容易被忽略但它是版本错配的后悔药。老客户端内置的是 2.x 版协议服务端下发 3.x 的文本如果客户端不判断直接渲染就会出现标题写 3.2、条款还是旧的这种翻车现场。placeholders白名单看着多余实际是防御性设计。文本里出现${company_name}但没在安装器里注入用户会看到一串原始占位符反过来如果允许任意变量替换文本作者随手写个${path}就可能被打包脚本误替换成构建机路径。白名单配合校验脚本两头都堵住。2.3 为什么不用一个纯文本文件了事最直接的替代方案是一个license.txt扔进安装器结束。这套做法的成本优势很明显但它在三个地方会立刻崩掉。第一是定位。审计方问3.2 版第 4 条讲的是什么纯文本没有稳定的条款标识只能靠从头数第几段。而资源包里的源文本用 Markdown 标题做条款编号抽取脚本能直接产出{clause: 4.2, text: ...}这样的结构任何一次查询都能落到确定的锚点。第二是比对。纯文本改了之后人眼 diff 只能看出这段变了看不出这段变了是否影响用户已同意的范围。资源包的做法是按条款生成子指纹条款级指纹不变的部分就不需要重新征求同意这条规则能显著减少发版时的弹窗打扰。第三是多语言。纯文本方案里多语言通常变成license_zh.txt、license_en.txt一堆散文件加一段 if-else。资源包用languages列表加回退优先级缺哪个语言就往下走逻辑收敛在一处。代价也有多了一层抽取和渲染构建时间会多一点文本维护者要遵守编号规范。我的判断是只要你的产品有两个以上语言、或者有私有化交付场景这笔投入就是值的纯内部工具、单语言、不对外分发那确实没必要上这套。3. 文本抽取与结构化把 eula 变成可查询的数据源文本进库之后第一件要做的不是渲染是抽取。抽取的意义在于把给人读的段落转成给程序判断的条款单元后面的版本比对、同意范围计算、留痕明细全依赖这一步的输出。3.1 条款切分脚本与编号规范切分规则必须和文本写法强绑定否则脚本会脆。约定是一级条款用## 4.二级条款用### 4.2正文段落跟在标题后面遇到下一个标题就收口。这个规范足够简单写作者不容易写错正则也好写。# tools/extract.py import json import re import sys from pathlib import Path import yaml # 一级## 4. 标题 二级### 4.1 标题 CLAUSE_RE re.compile(r^(#{2,3})\s(\d(?:\.\d)?)\.?\s(.*)$) def split_clauses(md_text: str): 按标题切分条款返回 [{clause, title, level, body}] clauses, cur [], None for raw in md_text.splitlines(): line raw.rstrip() m CLAUSE_RE.match(line) if m: if cur: clauses.append(cur) hashes, no, title m.groups() cur { clause: no, # 条款编号如 4 / 4.2 level: len(hashes) - 1, # 1一级2二级 title: title.strip(), body: [], } elif cur is not None: cur[body].append(line) if cur: clauses.append(cur) for c in clauses: # 段落合并连续空行折叠为一个避免指纹被空行数量影响 text \n.join(c[body]).strip() c[text] re.sub(r\n{2,}, \n\n, text) del c[body] return clauses def main(lang: str): root Path(__file__).resolve().parent.parent meta yaml.safe_load((root / meta/eula.yaml).read_text(encodingutf-8)) src root / texts / lang / eula.md clauses split_clauses(src.read_text(encodingutf-8)) out { id: meta[id], version: meta[version], revision: meta[revision], language: lang, count: len(clauses), clauses: clauses, } dst root / dist / feula.{lang}.json dst.parent.mkdir(parentsTrue, exist_okTrue) dst.write_text(json.dumps(out, ensure_asciiFalse, indent2), encodingutf-8) print(f[extract] {lang}: {len(clauses)} clauses - {dst}) if __name__ __main__: main(sys.argv[1] if len(sys.argv) 1 else zh-CN)脚本逻辑有三处值得说明。CLAUSE_RE用#{2,3}同时匹配两级标题靠捕获组的井号数量反推层级避免写两条正则后面对不上。段落合并时把连续空行折叠成两个换行是为了让指纹只对内容敏感、对排版不敏感——否则编辑在段落间多敲一个回车整份协议的指纹就变了留痕表里会凭空多出一批文本已变更的记录。输出落在dist/并按语言分文件是为了让渲染脚本和安装器脚本各取所需不用重复解析 Markdown。调用方式是python tools/extract.py zh-CN参数就是语言目录名必须和meta/eula.yaml的languages里某一项完全一致脚本不做大小写容错。这个严格是刻意的容错会导致构建机上能过、本地过不了排查起来很烦。写文本的人要守的规矩只有三条编号连续不跳号标题行只写编号和标题不写正文条款正文里不要出现以##开头的行。第三条最容易被违反有人在条款里贴了一段 Markdown 示例直接把切分打乱抽出来的条款数会莫名其妙变多。3.2 指纹计算整份指纹与条款级指纹指纹有两个粒度。整份指纹用于判断这份文本是否等同于上次发布的那份条款级指纹用于判断用户上次同意过的条款里哪些变了。两个都要缺一不可。# tools/fingerprint.py import hashlib import json import unicodedata from pathlib import Path import yaml ROOT Path(__file__).resolve().parent.parent def normalize(text: str) - str: 归一化去 BOM、统一换行、去行尾空白、压缩连续空格 text text.lstrip(\ufeff) text text.replace(\r\n, \n).replace(\r, \n) text \n.join(line.rstrip() for line in text.split(\n)) text unicodedata.normalize(NFKC, text) # 全角/半角、兼容字符归一 return text.strip() def sha256(text: str) - str: return hashlib.sha256(text.encode(utf-8)).hexdigest() def main(): meta_path ROOT / meta/eula.yaml meta yaml.safe_load(meta_path.read_text(encodingutf-8)) per_lang {} for lang in meta[languages]: raw (ROOT / texts / lang / eula.md).read_text(encodingutf-8) norm normalize(raw) clause_hashes {} data json.loads((ROOT / dist / feula.{lang}.json).read_text(encodingutf-8)) for c in data[clauses]: clause_hashes[c[clause]] sha256(normalize(c[title] \n c[text])) per_lang[lang] {doc: sha256(norm), clauses: clause_hashes} # 整份指纹取默认语言条款指纹按语言分别保存 meta[fingerprint][value] per_lang[meta[default_language]][doc] meta_path.write_text( yaml.safe_dump(meta, allow_unicodeTrue, sort_keysFalse), encodingutf-8 ) (ROOT / dist / fingerprint.json).write_text( json.dumps(per_lang, ensure_asciiFalse, indent2), encodingutf-8 ) print([fingerprint] doc , meta[fingerprint][value][:16], ...) # 与上一版比对输出变更条款清单供发版脚本判断是否需要重新征得同意 prev ROOT / dist / fingerprint.prev.json if prev.exists(): old json.loads(prev.read_text(encodingutf-8)) for lang in meta[languages]: changed [ k for k, v in per_lang[lang][clauses].items() if old.get(lang, {}).get(clauses, {}).get(k) ! v ] if changed: print(f[fingerprint] {lang} changed clauses: {sorted(changed)}) if __name__ __main__: main()normalize里四个动作对应四类真实翻车。去 BOM 是因为 Windows 编辑器保存 UTF-8 时常带 BOMLinux 构建机读到的首字符不同同一条款算出两个哈希。统一换行是因为 Git 的core.autocrlf在不同机器上配置不同同一份文件在两台机器上指纹不一致。去行尾空白是防止编辑器自动 trim。NFKC 归一化处理全角标点与兼容字符中文文本里全角逗号和半角逗号混用极其常见不做归一化指纹每天都在变。clause_hashes用title \n text拼起来算是为了让只改标题不改正文也算变更。条款编号本身不参与哈希这样把一个条款从 4.2 挪到 4.3 不会被判定为内容变更。fingerprint.prev.json的存在是给发版脚本用的变更条款清单为空说明只是排版动了用户不需要重新同意清单非空就得走阻断式重新确认。这个文件由构建流程负责在每次成功后重命名别手工维护。3.3 多语言对齐与回退策略多语言的坑不在翻译在对齐。texts/zh-CN/有 24 条texts/en-US/只有 23 条抽取脚本各自跑完都成功但条款级指纹对不上同意范围计算就会错位。校验放在抽取之后立刻做比对语言间的条款编号集合是否完全一致# tools/check_align.py import json from pathlib import Path import yaml ROOT Path(__file__).resolve().parent.parent meta yaml.safe_load((ROOT / meta/eula.yaml).read_text(encodingutf-8)) sets {} for lang in meta[languages]: data json.loads((ROOT / dist / feula.{lang}.json).read_text(encodingutf-8)) sets[lang] [c[clause] for c in data[clauses]] base_lang meta[default_language] base sets[base_lang] ok True for lang, nums in sets.items(): missing [n for n in base if n not in nums] extra [n for n in nums if n not in base] if missing or extra: ok False print(f[align] {lang}: missing{missing} extra{extra}) print([align] OK if ok else [align] FAILED) raise SystemExit(0 if ok else 1)回退策略写在languages的顺序里取第一个存在的语言取不到就用default_language再取不到直接构建失败——不允许静默降级成空字符串。静默降级的后果是安装器弹出一个空白协议页同意按钮还亮着用户点了也能过这种翻车最难受因为它在测试环境里往往复现不出来。关于机器翻译可以用于内部预览但不能直接进texts/。指纹机制会把机器翻译稿和人工稿一视同仁一旦发了版后面就没法区分哪份是正式文本。常见做法是加一个texts/lang/eula.draft.md的旁路目录抽取脚本默认不读只有显式传--include-draft才处理。4. 装机向导落地同意流程的三处集成点文本准备好之后真正的交付在三个地方安装器、客户端首启、留痕存储。三处的展示口径必须一致否则用户会看到两份措辞不同的协议信任度直接归零。4.1 安装器展示渲染产物与页面挂载安装器普遍对 Markdown 不友好所以要先渲染成纯文本或 RTF。渲染脚本的职责只有两个把占位符替换成实际值把 Markdown 标记压平成安装器能认的格式。# tools/render.py import json import sys from pathlib import Path import yaml ROOT Path(__file__).resolve().parent.parent def render(lang: str, values: dict): meta yaml.safe_load((ROOT / meta/eula.yaml).read_text(encodingutf-8)) data json.loads((ROOT / dist / feula.{lang}.json).read_text(encodingutf-8)) allowed set(meta[placeholders]) unknown set(values) - allowed if unknown: raise SystemExit(fplaceholder not in whitelist: {unknown}) lines [f{meta[id]} version {meta[version]}.{meta[revision]}, ] for c in data[clauses]: indent if c[level] 1 else lines.append(f{indent}{c[clause]}. {c[title]}) body c[text] for k, v in values.items(): body body.replace(${ k }, str(v)) lines.append(body) lines.append() text \n.join(lines) # 校验渲染后不允许残留占位符 if ${ in text: raise SystemExit(unresolved placeholder remains after render) out ROOT / dist / feula.{lang}.txt out.write_text(text, encodingutf-8, newline\r\n) # 安装器按 CRLF 更稳 print(f[render] {lang} - {out} ({len(text)} chars)) if __name__ __main__: render(sys.argv[1], { product_name: sys.argv[2] if len(sys.argv) 2 else 某客户端, company_name: 某公司, contact_mail: supportexample.invalid, })newline\r\n是刻意写的。安装器的许可页控件大多是原生 Windows 控件纯 LF 的文件在部分环境里会显示成一整行用户滚不动require_scroll的判定永远为真谁都没法点下一步。这个坑我在两个项目上各踩过一次。unresolved placeholder那条硬校验别删。文本里出现${contact_mail}而值没传安装器上就会显示原始占位符属于一眼可见的低级事故但偏偏很容易漏因为本地默认值往往填得挺全。NSIS 侧挂载许可页只要两行配合自定义的离开回调记录同意动作!define MUI_PAGE_CUSTOMFUNCTION_LEAVE OnLicenseLeave !insertmacro MUI_PAGE_LICENSE dist\eula.zh-CN.txt Function OnLicenseLeave ; $0 用于拼接留痕行写入安装目录下的 consent.log FileOpen $0 $INSTDIR\consent.log a FileWrite $0 langzh-CN$\r$\n FileWrite $0 version3.2.7$\r$\n FileWrite $0 ts$%DATE% $%TIME%$\r$\n FileClose $0 FunctionEndMUI_PAGE_CUSTOMFUNCTION_LEAVE在用户点下一步离开许可页时触发此时同意单选已被选中是写入留痕的正确时机——放进.onInstSuccess就晚了用户可能中途取消留痕会漏。写入用追加模式a避免重装时覆盖历史记录。路径用$INSTDIR是因为它此时已确定别写$TEMP临时目录会被清理留痕等于没留。4.2 客户端首启弹窗版本比对与阻断安装器只管安装那一刻客户端还得管运行期间协议升级。首启逻辑的判定顺序是读服务端或本地配置的最新版本 → 和用户已同意的版本比对 → 不一致则弹窗 → 必须滚到底才解锁同意按钮 → 不接受则退出。比对用(version, revision)元组不要用字符串比较。字符串比较下3.10 3.9会成立这个坑每年都有人踩。用 Python 写个比对函数就三行def is_newer(local: tuple, remote: tuple) - bool: local/remote 形如 (3, 2, 7)返回 remote 是否比 local 新 return tuple(int(x) for x in remote) tuple(int(x) for x in local)require_scroll的判定不要依赖滚动条位置百分比那个值在字体缩放、高 DPI 下不可靠。稳妥做法是给控件挂一个滚动到末尾事件事件触发后置一个布尔位。高 DPI 场景下滚动条的nPos最大值可能小于nMax所有基于位置的计算都会偏。弹窗关闭后无论同意与否都要落一条记录拒绝也是记录因为拒绝次数多了说明文本措辞有问题这是个有用的产品信号。4.3 留痕存储表结构与保留策略留痕表建议单独一个 SQLite 文件不要塞进业务库。理由是保留期不同业务库有备份和清理策略协议留痕的保留期由storage.keep_days控制混在一起会让清理逻辑互相打架。CREATE TABLE IF NOT EXISTS consent ( id INTEGER PRIMARY KEY AUTOINCREMENT, eula_id TEXT NOT NULL, version TEXT NOT NULL, revision INTEGER NOT NULL, lang TEXT NOT NULL, fingerprint TEXT NOT NULL, -- 当时的整份指纹 action TEXT NOT NULL, -- accept / decline channel TEXT NOT NULL, -- installer / first_run / upgrade machine_hash TEXT NOT NULL, -- 机器标识的哈希不存原始值 created_at TEXT NOT NULL ); CREATE INDEX IF NOT EXISTS idx_consent_ver ON consent(eula_id, version, revision); CREATE INDEX IF NOT EXISTS idx_consent_ts ON consent(created_at);fingerprint必须存。只存版本号的话同一版本号下的多次修订就无法区分事后无法证明用户同意的到底是哪份文本。这个字段是整个留痕表的价值所在。machine_hash存哈希不存原始机器码是出于数据最小化考虑。同一台机器多次同意会产生多行这是正常的别做去重合并——重装、换语言、协议升级都应该各留一条。保留策略由清理任务读取keep_days执行删除前先做一次归档导出CSV 或 JSON Lines别直接DELETE。见过直接在安装器里跑DELETE ... WHERE created_at ...的写法一旦日期格式解析出问题整表清空那真是没有后悔药。5. 避坑与排查五个能把发版卡住的真实问题下面五条都是我在拆这类资源包时真遇到过的按现象 → 原因 → 解决记。前三个偏文本与编码后两个偏集成与留痕。5.1 文本层的三个坑坑一同样的文件两台机器指纹不一致。现象是构建机上跑fingerprint.py得到的哈希和本地不同CI 因此判定文本变更触发了一次不必要的重新同意。 原因有两层一是 Git 在 Windows 上默认core.autocrlftrue检出时把 LF 换成了 CRLF二是某个编辑器在保存时加了 BOM。两者都会改变字节流。 解决办法是把归一化前置到所有读文件的地方normalize()里那四步一个都不能省同时在仓库根加.gitattributes对texts/**声明-text让 Git 不要做换行转换。做完这两步同一份内容在任何机器上算出的指纹都一致。坑二条款数突然变多。现象是抽取脚本输出的count从 24 变成 27check_align.py报某几个条款缺失。 原因是有编辑在条款正文里贴了一段以##开头的示例文本切分正则把它当成了新条款把原来的一条切成了三段。 解决办法是短期在编辑规范里加一条正文中禁止以井号开头长期在抽取脚本里加个断言相邻两个条款编号必须连续跳号就报错退出。我一般还会让extract.py输出一条告警列出所有一级条款编号肉眼扫一遍就知道有没有异常。坑三全角半角混用导致频繁误报变更。现象是没人改内容但fingerprint.json里的条款指纹每隔几天就变一次。 原因是不同人用不同输入法中文逗号和英文逗号、全角括号和半角括号混着来甚至同一个词有时候是全角空格分隔。 解决办法就是unicodedata.normalize(NFKC, text)它会把全角 ASCII 统一成半角、把兼容字符归一。注意 NFKC 会改动部分特殊字符的形态如果文本里有需要保持原样的符号要在归一化前做白名单保护。5.2 集成与留痕的两个坑坑四静默安装直接跳过了许可页。现象是批量部署的机器上留痕表一条记录都没有验收方认为未展示协议。 原因是安装器用了/S静默模式MUI_PAGE_LICENSE页面被跳过OnLicenseLeave根本不触发。 解决办法是在静默分支里显式补一条记录把channel标成installer_silent并在部署文档里写明静默安装视为已接受由部署方承担责任。代码上不要试图在静默模式下弹窗那会把自动化部署卡死。坑五升级后协议变了但用户没被重新询问。现象是服务端下发了 3.3 版文本客户端启动后界面显示的仍是 3.2 版用户也不会被要求重新同意。 原因有两个常见版本一是比对用了字符串比较3.10 3.9判断为假二是客户端把已同意版本缓存在注册表里升级安装包时把整个注册表键覆盖了缓存被重置成默认值 0.0反而变成未同意但 UI 又读的是安装目录里的旧文本。 解决办法是比对一律走整型元组缓存键带上eula_id前缀避免被同名键覆盖升级流程里加一步读旧缓存 → 迁移到新键 → 删旧键别直接删。6. 验收与进阶把 eula 纳入 CI 门禁到这一步文本、脚本、安装器集成都有了剩下的问题是怎么保证下次发版不退化。我的习惯是让构建流水线在打包之前先跑一遍校验任何一个检查失败就中断构建不允许先发出去再补。校验脚本写成纯 bash不依赖额外运行时放在tools/ci_check.sh#!/usr/bin/env bash set -euo pipefail LANG_DEFAULTzh-CN echo [ci] 1/6 抽取条款 python tools/extract.py $LANG_DEFAULT echo [ci] 2/6 多语言对齐 python tools/check_align.py echo [ci] 3/6 计算指纹 python tools/fingerprint.py echo [ci] 4/6 渲染安装器文本 python tools/render.py $LANG_DEFAULT 某客户端 echo [ci] 5/6 检查渲染产物无占位符残留 if grep -q \${ dist/eula.$LANG_DEFAULT.txt; then echo [ci] FAIL: unresolved placeholder; exit 1 fi echo [ci] 6/6 检查产物非空且条款数达标 test -s dist/eula.$LANG_DEFAULT.json python - PY import json, sys data json.load(open(dist/eula.zh-CN.json, encodingutf-8)) if data[count] 10: print([ci] FAIL: clause count too low:, data[count]); sys.exit(1) print([ci] clause count , data[count]) PY echo [ci] ALL PASSEDset -euo pipefail是必须的少了pipefail中间某个 python 命令失败会被管道吞掉脚本照样输出 PASSED。第 5 步用grep -q \${做兜底检查因为渲染脚本内部的校验万一被改坏了这一步能独立拦住。第 6 步的条款数下限用 10 是个经验值——不是精确断言而是防止抽取脚本读错了文件这种低级错误把空结果当成成功。这个下限每次协议大改时都要复核一遍别让它变成一个永远为真的摆设。配合 CI还需要一份版本升级的回归清单。这份清单我通常会写成表格贴在发布流程文档里每次动协议文本就照着走一遍触发条件必须执行的动作判定依据仅修正错别字递增revision不弹窗条款级指纹全部未变条款实质变化递增version阻断式重新同意至少一个条款指纹变化新增语言补languages列表并跑对齐检查check_align.py通过客户端大版本升级复核min_app_version老客户端不展示新文本留痕清理策略调整先导出归档再删归档文件行数与表内一致有一点值得单独说min_app_version这个字段在真实发版里经常被忘掉结果服务端配了新版协议一批还在用旧客户端的机器启动后取到新文本UI 又不会渲染新增的条款编号用户看到的是缺号的协议观感极差。我后来把这个字段接进了客户端的启动自检本地版本低于min_app_version就不拉取远端文本只用内置版本并把这条判定写进启动日志。最后提一个进阶玩法——把条款级指纹接进差异通知。发版前跑一次比对如果变更条款清单非空就自动把变更的条款编号和标题整理成一段摘要附在发布单里。审核的人不用打开完整协议只看这几条就能判断要不要重新走一遍确认流程。这一步做完协议文本才算真正从一段话变成了一个有状态、可追溯的工程对象。从那以后我每次接新的安装包项目第一件事就是把texts/和meta/两棵树立起来先跑通extract → fingerprint → render这条链再动安装器脚本——顺序反过来后面必然要返工。希望帮到你。本文还有配套的精品资源点击获取
