diff --git a/.env.example b/.env.example index e7dbc59ac..ac31e1dd9 100644 --- a/.env.example +++ b/.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. diff --git a/deploy/container/api-server.env.example b/deploy/container/api-server.env.example index b4e0286b1..55f051ba0 100644 --- a/deploy/container/api-server.env.example +++ b/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 diff --git a/deploy/env/api-server.env.example b/deploy/env/api-server.env.example index c97ad913c..3cd99970f 100644 --- a/deploy/env/api-server.env.example +++ b/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 diff --git a/docs/technical/【技术方案】客户端本地埋点与主站入库契约-2026-09-21.md b/docs/technical/【技术方案】客户端本地埋点与主站入库契约-2026-09-21.md index 3b6b8be97..411158929 100644 --- a/docs/technical/【技术方案】客户端本地埋点与主站入库契约-2026-09-21.md +++ b/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 映射，不为每次上传另生成主站产品事件。