补齐客户端埋点环境变量示例

补充本地、生产及容器的埋点 origin 配置示例和 dev/release 说明。
同步技术方案中的运行时配置入口与地址匹配要求。

.env.example

@@ -239,6 +239,12 @@ GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR="false"
 # Windows/macOS 是系统维度，不填写 dev-win/dev-mac。
 GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL="dev"
 
+# 客户端埋点接收绑定的公开 origin，由 API Server 运行时读取；修改后重启服务。
+# 必须与客户端登录地址一致，不带 /api、路径或尾部斜杠；未配置/非法时上传接口返回 503。
+# 本地端口按实际启动结果填写（端口漂移后需同步），localhost 与 127.0.0.1 不可混用。
+# dev 使用 https://dev.genarrative.world；release 使用 https://www.genarrative.world。
+GENARRATIVE_AGC_ANALYTICS_ORIGIN="http://127.0.0.1:8082"
+
 # Optional: official VikingDB credentials for regenerating build-tag similarities
 # with the Python embedding script. The script auto-loads `.env.local` and uses
 # the fixed `bge-large-zh` embedding model.

deploy/container/api-server.env.example

@@ -5,6 +5,11 @@
 GENARRATIVE_ENV=container
 GENARRATIVE_API_HOST=0.0.0.0
 GENARRATIVE_API_PORT=8082
+# 客户端埋点接收绑定的公开 origin，由 API Server 运行时读取；修改后重启服务。
+# 必须与客户端登录地址一致，不带 /api、路径或尾部斜杠；未配置/非法时上传接口返回 503。
+# 以下为 compose 默认宿主机入口；更改映射端口或接入域名时同步修改，不填容器内部地址。
+# dev 使用 https://dev.genarrative.world；release 使用 https://www.genarrative.world。
+GENARRATIVE_AGC_ANALYTICS_ORIGIN=http://127.0.0.1:18080
 GENARRATIVE_API_LOG=info,tower_http=info
 GENARRATIVE_API_LISTEN_BACKLOG=1024
 GENARRATIVE_API_WORKER_THREADS=4

deploy/env/api-server.env.example

@@ -4,6 +4,10 @@
 GENARRATIVE_ENV=production
 GENARRATIVE_API_HOST=127.0.0.1
 GENARRATIVE_API_PORT=8082
+# 客户端埋点接收绑定的公开 origin，由 API Server 运行时读取；修改后重启服务。
+# 必须与客户端登录地址一致，不带 /api、路径或尾部斜杠；未配置/非法时上传接口返回 503。
+# 以下为 release；dev 部署改为 https://dev.genarrative.world。
+GENARRATIVE_AGC_ANALYTICS_ORIGIN=https://www.genarrative.world
 GENARRATIVE_API_LOG=info,tower_http=info
 GENARRATIVE_API_LISTEN_BACKLOG=1024
 GENARRATIVE_API_WORKER_THREADS=4

docs/technical/【技术方案】客户端本地埋点与主站入库契约-2026-09-21.md

@@ -611,6 +611,7 @@ session.json 是本地恢复元数据，不是待上传事件；事件文件不
 - 批次与所有事件的 user_id 必须相同且等于鉴权主体；匿名、未知 origin 批次不上传，不补认领到后来登录的账号。
 - destination_origin 必须匹配当前服务部署的可信公开 origin 配置，不使用未经信任的 Host 头作为判据。
 - 接收端配置 `GENARRATIVE_AGC_ANALYTICS_ORIGIN` 为规范 origin（无路径和尾部斜杠）：正式站 `https://www.genarrative.world`，测试站 `https://dev.genarrative.world`，本地联调填写客户端实际连接的 loopback origin。未配置/非法配置时接口返回 503，不猜测默认站点；允许 HTTPS 和本地 loopback HTTP。
+- 该变量在 API Server 运行时注入，修改后重启服务；客户端与管理后台无需新增埋点构建变量。配置示例见根目录 `.env.example`（本地默认 `http://127.0.0.1:8082`）、`deploy/env/api-server.env.example`（release，并注明 dev 值）与 `deploy/container/api-server.env.example`（compose 默认宿主机入口 `http://127.0.0.1:18080`）。实际端口、映射或域名变化时同步修改，始终与客户端登录地址一致。
 - 复用现有事件版本、枚举、字段长度与必填 nullable 校验；批内重复 event_id、未知字段或非法事件整批拒绝。
 - 本接口不进入普通成功路由 tracking 映射，不为每次上传另生成主站产品事件。