私有包仓库

何时需要这个

如果你的项目依赖托管在私有 registry 上的内部或专有 Python 包，而不是公共 PyPI，那么你需要：

告诉 UV 去哪里查找该包（一个 index URL）
告诉 UV 哪些包来自该 index（source mapping）
提供凭据，以便 UV 在安装时进行认证

CrewAI AMP 使用 UV 进行依赖解析和安装。 UV 通过 pyproject.toml 配置结合凭据环境变量，支持经过认证的私有 registry。

第 1 步：配置 pyproject.toml

你的 pyproject.toml 中有三部分需要协同工作：

1a. 声明依赖

像其他依赖一样，将私有包加入 [project.dependencies]：

[project]
dependencies = [
    "crewai[tools]>=0.100.1,<1.0.0",
    "my-private-package>=1.2.0",
]

1b. 定义 index

将你的私有 registry 注册为 [[tool.uv.index]] 下的命名 index：

[[tool.uv.index]]
name = "my-private-registry"
url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
explicit = true

1c. 将包映射到 index

使用 [tool.uv.sources] 告诉 UV 哪些包应该从你的私有 index 解析：

[tool.uv.sources]
my-private-package = { index = "my-private-registry" }

完整示例

[project]
name = "my-crew-project"
version = "0.1.0"
requires-python = ">=3.10,<=3.13"
dependencies = [
    "crewai[tools]>=0.100.1,<1.0.0",
    "my-private-package>=1.2.0",
]

[tool.crewai]
type = "crew"

[[tool.uv.index]]
name = "my-private-registry"
url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
explicit = true

[tool.uv.sources]
my-private-package = { index = "my-private-registry" }

更新 pyproject.toml 后，重新生成 lock 文件：

uv lock

第 2 步：设置认证凭据

UV 使用遵循命名规则的环境变量对私有 index 进行认证，该规则基于你在 pyproject.toml 中定义的 index 名称：

UV_INDEX_{UPPER_NAME}_USERNAME
UV_INDEX_{UPPER_NAME}_PASSWORD

其中 {UPPER_NAME} 是你的 index 名称转换为大写，并将连字符替换为下划线。

例如，名为 my-private-registry 的 index 会使用：

变量	值
`UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME`	你的 registry 用户名或 token 名称
`UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD`	你的 registry 密码或 token/PAT

Registry 提供方参考

下表展示了常见 registry 提供方的 index URL 格式和凭据值。请将占位符替换为你实际的组织和 feed 详情。

提供方	Index URL	用户名	密码
Azure DevOps Artifacts	`https://pkgs.dev.azure.com/{org}/_packaging/{feed}/pypi/simple/`	任意非空字符串（例如 `token`）	具有 Packaging Read 权限范围的 Personal Access Token（PAT）
GitHub Packages	`https://pypi.pkg.github.com/{owner}/simple/`	GitHub 用户名	具有 `read:packages` 权限范围的 Personal Access Token（classic）
GitLab Package Registry	`https://gitlab.com/api/v4/projects/{project_id}/packages/pypi/simple/`	`__token__`	具有 `read_api` 权限范围的 Project 或 Personal Access Token
AWS CodeArtifact	使用 `aws codeartifact get-repository-endpoint` 返回的 URL	`aws`	由 `aws codeartifact get-authorization-token` 获取的 token
Google Artifact Registry	`https://{region}-python.pkg.dev/{project}/{repo}/simple/`	`_json_key_base64`	base64 编码的 service account key
JFrog Artifactory	`https://{instance}.jfrog.io/artifactory/api/pypi/{repo}/simple/`	用户名或邮箱	API key 或 identity token
Self-hosted（devpi、Nexus 等）	你的 registry simple API URL	registry 用户名	registry 密码

在 AMP 中设置环境变量

私有 registry 凭据必须作为环境变量配置在 CrewAI AMP 中。你有两个选项：

Web Interface

登录 CrewAI AMP
导航到你的 automation
打开 Environment Variables 选项卡
为每个变量（UV_INDEX_*_USERNAME 和 UV_INDEX_*_PASSWORD）添加其值

详情请参阅 Deploy to AMP - Set Environment Variables 步骤。

CLI Deployment

在运行 crewai deploy create 之前，将变量添加到本地 .env 文件中。 CLI 会安全地将它们传输到平台：

OPENAI_API_KEY=sk-...
UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat-here

crewai deploy create

要更新现有部署上的凭据，请参阅 Update Your Crew - Environment Variables。

它们如何协同工作

当 CrewAI AMP 构建你的 automation 时，解析流程如下：

Build 开始

AMP 拉取你的仓库并读取 pyproject.toml 和 uv.lock。
UV 解析依赖

UV 读取 [tool.uv.sources]，以确定每个包应从哪个 index 获取。
UV 进行认证

对于每个私有 index，UV 会从你在 AMP 中配置的环境变量中查找 UV_INDEX_{NAME}_USERNAME 和 UV_INDEX_{NAME}_PASSWORD。
安装包

UV 下载并安装所有包 - 包括公共包（来自 PyPI）和私有包（来自你的 registry）。
Automation 运行

你的 crew 或 flow 会在所有依赖可用的情况下启动。

故障排查

构建期间认证错误

症状：在解析私有包时，构建失败并出现 401 Unauthorized 或 403 Forbidden。

检查：

UV_INDEX_* 环境变量名称是否与 index 名称完全匹配（大写，连字符 → 下划线）
凭据是否设置在 AMP 环境变量中，而不只是本地 .env
你的 token/PAT 是否具有包 feed 所需的读取权限
token 是否过期（尤其是 AWS CodeArtifact）

找不到包

症状：No matching distribution found for my-private-package。

检查：

pyproject.toml 中的 index URL 是否以 /simple/ 结尾
[tool.uv.sources] 条目是否将正确的包名映射到正确的 index 名称
该包是否确实已发布到你的私有 registry
使用相同凭据在本地运行 uv lock，验证解析是否正常

Lock 文件冲突

症状：在添加私有 index 后，uv lock 失败或产生意外结果。

解决方案：在本地设置凭据并重新生成：

export UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
export UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat
uv lock

然后提交更新后的 uv.lock。