From e1f20a6099ab09ba4b15365325274c3616c5bd8a Mon Sep 17 00:00:00 2001 From: Winoren <158550716+Winoren@users.noreply.github.com> Date: Sun, 18 Oct 2026 08:27:21 +0800 Subject: [PATCH] docs(docker): document the locked PyPI index requirement (#7011) * docs(docker): keep UV_INDEX_URL on the index pinned by uv.lock The README told users on restricted networks to export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple, but the gateway image installs with `uv sync --locked` and uv.lock is locked to https://pypi.org/simple, so any other index fails the build with "The lockfile at `uv.lock` needs to be updated, but `--locked` was provided" (#7003). Document the constraint instead of the mirror: name the pinned index, quote the exact failure, and note that installing from a mirror requires regenerating the lock or dropping --locked. CONTRIBUTING.md already showed the working value and gains the same note, and README_pt.md and README_ko.md carried the same sentence and are updated to match. * docs(docker): correct the NPM_REGISTRY scope and qualify the repro NPM_REGISTRY is not frontend-only: the gateway build also consumes it. docker/docker-compose.yaml (lines 95 and 117) and docker/docker-compose-dev.yaml (lines 154 and 189) pass it as a build arg to both the frontend and the gateway image, and backend/Dockerfile declares ARG NPM_REGISTRY (line 16) and applies it via npm config set registry (line 43) for the @larksuite/cli install. While re-verifying the uv repro on this head, also found that the quoted uv sync --locked --check only discriminates between indexes when the local environment is already in sync; if the environment is stale it reports the stale environment for either index. Point at uv lock --check for that case. Reported-by: willem-bd --------- Co-authored-by: D41910 --- CONTRIBUTING.md | 2 ++ README.md | 2 +- README_ko.md | 2 +- README_pt.md | 2 +- 4 files changed, 5 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b830776fa8..459b96689e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -105,6 +105,8 @@ export UV_INDEX_URL=https://pypi.org/simple export NPM_REGISTRY=https://registry.npmjs.org ``` +Keep `UV_INDEX_URL` at `https://pypi.org/simple`: the gateway image installs with `uv sync --locked`, and `uv.lock` is locked to that index, so a mirror makes the build fail with ``The lockfile at `uv.lock` needs to be updated, but `--locked` was provided``. + #### Recommended host resources Use these as practical starting points for development and review environments: diff --git a/README.md b/README.md index 554a6b40da..79f6403eb6 100644 --- a/README.md +++ b/README.md @@ -483,7 +483,7 @@ make docker-logs # View logs `make docker-start` starts `provisioner` only when `config.yaml` uses provisioner mode (`sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider` with `provisioner_url`). -Docker builds use the upstream `uv` registry by default. If you need faster mirrors in restricted networks, export `UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple` and `NPM_REGISTRY=https://registry.npmmirror.com` before running `make docker-init` or `make docker-start`. +Docker builds use the upstream `uv` registry by default. The gateway image installs with `uv sync --locked`, and `uv.lock` pins `https://pypi.org/simple`, so `UV_INDEX_URL` has to keep that value: exporting a mirror such as `https://pypi.tuna.tsinghua.edu.cn/simple` fails the build with ``The lockfile at `uv.lock` needs to be updated, but `--locked` was provided`` (reproduce in an already-synced environment with `cd backend && UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv sync --locked --check`; if the environment itself is stale, `--check` reports that instead for either index, so use `uv lock --check` to see it without syncing). Installing from a mirror requires regenerating the lock or dropping `--locked`, and both change what the image installs, so keep the default index for a checkout you intend to contribute back. `NPM_REGISTRY=https://registry.npmmirror.com` is independent of this: it applies to the frontend image's `pnpm` install and to the gateway image's Lark CLI install (`@larksuite/cli`, which `backend/Dockerfile` installs with npm). Local AIO sandbox control traffic is always direct: loopback/private addresses, single-label cluster hosts, and Docker/Podman internal hostnames do not inherit diff --git a/README_ko.md b/README_ko.md index af79fda14a..a1863c29c2 100644 --- a/README_ko.md +++ b/README_ko.md @@ -372,7 +372,7 @@ make docker-logs # View logs `make docker-start`는 `config.yaml`이 provisioner 모드(`sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider`와 `provisioner_url` 사용)를 쓰는 경우에만 `provisioner`를 시작합니다. -Docker 빌드는 기본적으로 업스트림 `uv` 레지스트리를 사용합니다. 제한된 네트워크에서 더 빠른 미러가 필요하다면 `UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple`과 `NPM_REGISTRY=https://registry.npmmirror.com`을 export한 뒤 `make docker-init` 또는 `make docker-start`를 실행하세요. +Docker 빌드는 기본적으로 업스트림 `uv` 레지스트리를 사용합니다. 게이트웨이 이미지는 `uv sync --locked`로 설치하고 `uv.lock`은 `https://pypi.org/simple`를 고정하므로, `UV_INDEX_URL`은 이 값을 유지해야 합니다. `https://pypi.tuna.tsinghua.edu.cn/simple` 같은 미러를 export하면 ``The lockfile at `uv.lock` needs to be updated, but `--locked` was provided`` 오류로 빌드가 실패합니다(이미 동기화된 환경에서 `cd backend && UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv sync --locked --check`로 재현 가능; 환경 자체가 오래된 경우에는 어떤 인덱스에서도 환경 갱신만 안내하므로, 동기화 없이 확인하려면 `uv lock --check`를 사용하세요). 미러에서 설치하려면 lock을 다시 생성하거나 `--locked`를 제거해야 하며, 둘 다 이미지에 설치되는 내용이 달라지므로 기여할 체크아웃에서는 기본 인덱스를 유지하세요. `NPM_REGISTRY=https://registry.npmmirror.com`은 이와 무관하며, 프론트엔드 이미지의 `pnpm` 설치와 게이트웨이 이미지의 Lark CLI 설치(`backend/Dockerfile`이 npm으로 설치하는 `@larksuite/cli`)에 적용됩니다. 로컬 AIO 샌드박스의 제어 트래픽은 항상 직접 연결됩니다. 루프백/사설 주소, 단일 레이블 클러스터 호스트, Docker/Podman 내부 호스트 이름은 `HTTP_PROXY`나 `HTTPS_PROXY`를 상속하지 않습니다. 외부 샌드박스 FQDN과 공인 IP는 여전히 환경 변수의 프록시 설정을 따릅니다. diff --git a/README_pt.md b/README_pt.md index 4108b23d0d..470e9966d7 100644 --- a/README_pt.md +++ b/README_pt.md @@ -329,7 +329,7 @@ make docker-logs # View logs O `make docker-start` só inicia o `provisioner` quando o `config.yaml` usa o modo provisioner (`sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider` com `provisioner_url`). -Os builds do Docker usam o registry upstream do `uv` por padrão. Se você precisa de mirrors mais rápidos em redes restritas, exporte `UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple` e `NPM_REGISTRY=https://registry.npmmirror.com` antes de rodar `make docker-init` ou `make docker-start`. +Os builds do Docker usam o registry upstream do `uv` por padrão. A imagem do gateway instala com `uv sync --locked` e o `uv.lock` fixa `https://pypi.org/simple`, portanto `UV_INDEX_URL` precisa manter esse valor: exportar um mirror como `https://pypi.tuna.tsinghua.edu.cn/simple` faz o build falhar com ``The lockfile at `uv.lock` needs to be updated, but `--locked` was provided`` (reproduza em um ambiente já sincronizado com `cd backend && UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv sync --locked --check`; se o ambiente em si estiver desatualizado, `--check` informa apenas isso para qualquer índice, então use `uv lock --check` para ver o erro sem sincronizar). Instalar a partir de um mirror exige regerar o lock ou remover `--locked`, e as duas opções mudam o que a imagem instala, então mantenha o índice padrão em um checkout que você pretende contribuir de volta. `NPM_REGISTRY=https://registry.npmmirror.com` é independente disso e se aplica à instalação `pnpm` da imagem do frontend e à instalação do Lark CLI na imagem do gateway (`@larksuite/cli`, que o `backend/Dockerfile` instala com npm). O tráfego de controle do sandbox AIO local é sempre direto: endereços de loopback/privados, hosts de cluster de rótulo único e hostnames internos do Docker/Podman não herdam `HTTP_PROXY` nem `HTTPS_PROXY`. FQDNs externos de sandbox e IPs públicos continuam respeitando as configurações de proxy do ambiente.