From 035a7f482b558dfaa8cd5751c25e28a8d714c63c Mon Sep 17 00:00:00 2001 From: J Date: Fri, 5 Jun 2026 15:56:41 +0800 Subject: [PATCH] docs(lark): fix ops guidance to match auto per-installation region MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review follow-up (MUL-3083). .env.example and docker-compose.selfhost.yml still told operators that international Lark requires pointing both base URLs at open.larksuite.com — now wrong, and it would push a fresh deployment back into a single-cloud override. Rewrite them: the base URLs are optional deployment-wide overrides; normal dual-cloud operation keeps them empty. Document the first-boot auto-relabel for deployments migrating off the old single-cloud override, across the integration docs (en/zh/ja/ko). MUL-3083 Co-authored-by: multica-agent --- .env.example | 13 +++++++++---- apps/docs/content/docs/lark-bot-integration.ja.mdx | 2 ++ apps/docs/content/docs/lark-bot-integration.ko.mdx | 2 ++ apps/docs/content/docs/lark-bot-integration.mdx | 2 ++ apps/docs/content/docs/lark-bot-integration.zh.mdx | 2 ++ docker-compose.selfhost.yml | 13 ++++++++----- 6 files changed, 25 insertions(+), 9 deletions(-) diff --git a/.env.example b/.env.example index c756c7e332..650e298930 100644 --- a/.env.example +++ b/.env.example @@ -205,10 +205,15 @@ GITHUB_WEBHOOK_SECRET= # that encrypts each Bot's app secret at rest. Leave empty to disable. # Generate one with: openssl rand -base64 32 MULTICA_LARK_SECRET_KEY= -# The two base URLs default to the mainland host (open.feishu.cn). For -# international Lark tenants, set BOTH to https://open.larksuite.com: -# HTTP drives outbound Open Platform API calls, CALLBACK drives the -# inbound long-conn callback bootstrap. See docs/lark-bot-integration. +# Mainland 飞书 and international Lark are auto-detected per installation +# (at QR scan) and served side by side — LEAVE THESE EMPTY for normal use. +# They are optional deployment-wide overrides that force EVERY installation +# onto one host (a proxy, a mock for tests, or a single-cloud staging +# setup); HTTP drives outbound Open Platform API calls, CALLBACK the inbound +# long-conn bootstrap. NOTE: if you previously ran international Lark by +# setting these to https://open.larksuite.com, the server relabels your +# existing installs to region=lark on first boot after upgrade, so you can +# clear these afterwards. See docs/lark-bot-integration. MULTICA_LARK_HTTP_BASE_URL= MULTICA_LARK_CALLBACK_BASE_URL= diff --git a/apps/docs/content/docs/lark-bot-integration.ja.mdx b/apps/docs/content/docs/lark-bot-integration.ja.mdx index a6b46fc026..86497d693b 100644 --- a/apps/docs/content/docs/lark-bot-integration.ja.mdx +++ b/apps/docs/content/docs/lark-bot-integration.ja.mdx @@ -83,6 +83,8 @@ Multica Cloud では連携はすでに利用可能です——このセクショ **Feishu と Lark 国際版の両対応。** 各 Bot がどのクラウド（中国大陸の Feishu = `open.feishu.cn`、国際版 Lark = `open.larksuite.com`）に属するかは、QR コードをスキャンした時点で自動的に判定され、そのインストールに保存されて、その Bot へのすべての呼び出しに使われます。1 つのデプロイで両方を同時に提供できるため、どちらのテナントのチームも追加設定なしでバインドできます。 `MULTICA_LARK_HTTP_BASE_URL` / `MULTICA_LARK_CALLBACK_BASE_URL` は、デプロイ全体を上書きする任意のオプション（プロキシやモック用）としてのみ残っています。通常運用では未設定のままにして、各インストールがそれぞれのクラウドに到達するようにしてください。 + +**単一クラウド構成からのアップグレード？** これらを `https://open.larksuite.com` に設定して国際版 Lark を運用していた場合、アップグレード後の初回起動時にサーバーが既存のインストールを Lark リージョンへ付け替えるので、その後はこの上書きを外せます。中国大陸の Feishu デプロイでは操作は不要です。 ## 次に diff --git a/apps/docs/content/docs/lark-bot-integration.ko.mdx b/apps/docs/content/docs/lark-bot-integration.ko.mdx index 2bde10ccb3..f5e12a274b 100644 --- a/apps/docs/content/docs/lark-bot-integration.ko.mdx +++ b/apps/docs/content/docs/lark-bot-integration.ko.mdx @@ -83,6 +83,8 @@ Multica Cloud에서는 연동이 이미 사용 가능합니다 — 이 섹션은 **Feishu와 Lark 국제판을 동시에 지원.** 각 Bot이 어느 클라우드(중국 본토 Feishu = `open.feishu.cn`, 국제판 Lark = `open.larksuite.com`)에 속하는지는 QR 코드를 스캔할 때 자동으로 감지되어 해당 설치에 저장되고, 그 Bot에 대한 모든 호출에 사용됩니다. 하나의 배포로 둘을 동시에 제공하므로, 어느 테넌트의 팀이든 추가 설정 없이 바인딩할 수 있습니다. `MULTICA_LARK_HTTP_BASE_URL` / `MULTICA_LARK_CALLBACK_BASE_URL`는 배포 전체를 덮어쓰는 선택적 오버라이드(프록시나 mock용)로만 남아 있습니다. 일반 운영에서는 설정하지 않은 채로 두어 각 설치가 자기 클라우드에 도달하도록 하세요. + +**단일 클라우드 구성에서 업그레이드하나요?** 이 변수들을 `https://open.larksuite.com`으로 설정해 국제판 Lark를 운영했다면, 업그레이드 후 첫 부팅 시 서버가 기존 설치를 Lark 리전으로 다시 표시하므로 이후에는 오버라이드를 지울 수 있습니다. 중국 본토 Feishu 배포에서는 별도 작업이 필요 없습니다. ## 다음 diff --git a/apps/docs/content/docs/lark-bot-integration.mdx b/apps/docs/content/docs/lark-bot-integration.mdx index a88c799801..87b6e5d46b 100644 --- a/apps/docs/content/docs/lark-bot-integration.mdx +++ b/apps/docs/content/docs/lark-bot-integration.mdx @@ -83,6 +83,8 @@ For self-host, Lark is **off until you set an at-rest encryption key**. The key **Feishu and Lark international, side by side.** The cloud each Bot belongs to — mainland Feishu (`open.feishu.cn`) or Lark international (`open.larksuite.com`) — is detected automatically when you scan the QR, stored on the installation, and used for every call to that Bot. A single deployment serves both at once, so teams on either tenant can bind without any extra configuration. The `MULTICA_LARK_HTTP_BASE_URL` / `MULTICA_LARK_CALLBACK_BASE_URL` env vars remain only as an optional deployment-wide override (a proxy or a mock); leave them unset for normal operation so each installation keeps reaching its own cloud. + +**Upgrading from a single-cloud setup?** If you ran an international-Lark deployment by setting those vars to `https://open.larksuite.com`, the server relabels your existing installations to the Lark region on first boot after upgrade — you can then clear the override. Mainland deployments need no action. ## Next diff --git a/apps/docs/content/docs/lark-bot-integration.zh.mdx b/apps/docs/content/docs/lark-bot-integration.zh.mdx index 78e7555700..82d1e60dac 100644 --- a/apps/docs/content/docs/lark-bot-integration.zh.mdx +++ b/apps/docs/content/docs/lark-bot-integration.zh.mdx @@ -83,6 +83,8 @@ import { Callout } from "fumadocs-ui/components/callout"; **同时支持飞书与海外版 Lark。** 每个 Bot 属于哪个云——中国大陆飞书（`open.feishu.cn`）还是海外版 Lark（`open.larksuite.com`）——会在你扫码时自动识别、记录在该安装上，并用于对这个 Bot 的所有调用。同一个部署可以同时服务两者，因此两个租户的团队都能直接绑定，无需任何额外配置。 `MULTICA_LARK_HTTP_BASE_URL` / `MULTICA_LARK_CALLBACK_BASE_URL` 仅作为可选的部署级覆盖项保留（用于代理或 mock）；正常运行时请保持不设置，让每个安装各自连到自己的云。 + +**从单云部署升级？** 如果你之前是把这两个变量设为 `https://open.larksuite.com` 来跑海外版 Lark，升级后服务会在首次启动时自动把存量安装重标记为 Lark region，之后你就可以清掉这个覆盖项。国内飞书部署无需任何操作。 ## 下一步 diff --git a/docker-compose.selfhost.yml b/docker-compose.selfhost.yml index 92f829a5a0..db089cce1c 100644 --- a/docker-compose.selfhost.yml +++ b/docker-compose.selfhost.yml @@ -98,11 +98,14 @@ services: # "127.0.0.1/32" when running behind a same-host reverse proxy. MULTICA_TRUSTED_PROXIES: ${MULTICA_TRUSTED_PROXIES:-} # Lark / Feishu bot integration. MULTICA_LARK_SECRET_KEY is the - # opt-in: unset = integration disabled. The two base-URL knobs - # default to the mainland host (open.feishu.cn); international Lark - # tenants must point BOTH at https://open.larksuite.com — one drives - # outbound Open Platform API calls, the other the inbound long-conn - # callback bootstrap. See docs/lark-bot-integration. + # opt-in: unset = integration disabled. Mainland 飞书 and international + # Lark are auto-detected per installation and served side by side, so + # the two base-URL knobs should normally stay EMPTY. They are optional + # deployment-wide overrides that force every installation onto one host + # (proxy / mock / single-cloud staging). Upgrading from a setup that + # used https://open.larksuite.com here? The server relabels existing + # installs to region=lark on first boot, then you can clear them. + # See docs/lark-bot-integration. MULTICA_LARK_SECRET_KEY: ${MULTICA_LARK_SECRET_KEY:-} MULTICA_LARK_HTTP_BASE_URL: ${MULTICA_LARK_HTTP_BASE_URL:-} MULTICA_LARK_CALLBACK_BASE_URL: ${MULTICA_LARK_CALLBACK_BASE_URL:-}