`twine upload` 报 401，或 `pip install` 提示 `No matching distribution found`——多半不是包坏了，而是私服还没接对：服务没起来、**上传地址和安装索引搞混**、`username` 没写成 `__token__`，或 index-url 漏了 `/simple/`。

下面用 AngusRepo **社区版私有化部署**，按操作顺序走完一遍：**安装 → 建仓与令牌 → .pypirc / pip.conf → 最小包上传与安装 → 验证**。命令里的主机写成 **`repo.example.com`**，换成你的域名即可。

## 1. 安装（得到可打开的控制台）

前提：Docker Engine + Compose v2；约 2 核 / 4 GB；放行 **80**；`gm.example.com` 与 `repo.example.com` 已解析到本机（试用可写 `/etc/hosts`）。完整步骤见 第一次跑通。

```bash
curl --fail --location --progress-bar -o AngusRepo-Community-1.0.0.zip \
  https://repo.anguskit.com/raw/raw-public/AngusKit/repo/AngusRepo-Community-1.0.0.zip
unzip AngusRepo-Community-1.0.0.zip
cd AngusRepo-1.0.0
./install.sh
```

向导与快速开始对齐：Compose；Access 选 **2**（捆绑反代）；TLS 选 **4**（HTTP `:80`）；Database 选 Compose 内 MySQL；Public DNS name 填后缀如 `example.com`。出现 `Install finished.` 后：

```bash
./bin/angusctl.sh doctor   # 看到 doctor: OK
```

浏览器打开 `http://gm.example.com/` 登录，再打开 `http://repo.example.com/`。Windows 用 `curl.exe` + `.\install.bat`。需要 HTTPS 时见 安装与部署。

下文默认 **HTTP 私有化**。HTTP 下 pip 通常要加 `trusted-host`；上了可信证书后改成 `https://` 并可去掉该项。控制台能打开后，先建仓库和令牌，再改客户端配置。

## 2. 建仓、令牌与拓扑

`twine upload` 只能进 **HOSTED**；PROXY、GROUP 只读。在 `http://repo.example.com/` 创建：

| 仓库名示例 | 类型 | 干什么 |
| --- | --- | --- |
| `pypi-hosted` | HOSTED | twine 上传目标；建议禁止覆盖 |
| `pypi-proxy` | PROXY | 代理 PyPI（远程 URL：`https://pypi.org`） |
| `pypi-all` | GROUP | pip 统一安装入口；成员顺序 hosted → proxy |

![PyPI 私服拓扑：twine 上传到 HOSTED，pip 经 GROUP 安装](https://developer.qcloudimg.com/http-save/yehe-1099973/55030d10bfc5644cfd6b8200e930b86d.png)
两套路径不要混：

- **上传**：`/pypi/<仓库名>/`（HOSTED 根路径）
- **安装**：`/pypi/<仓库名>/simple/`（必须带 `/simple/`，PEP 503）

同一控制台继续准备：

- [ ] 创建访问令牌（只显示一次，立刻保存）
- [ ] CI 对 `pypi-hosted` 有 Write；开发者对 `pypi-all` 有 Read
- [ ] GROUP 成员顺序确认为 hosted → pypi-proxy

```bash
export REPO_TOKEN="your_access_token"
export REPO_HOST="repo.example.com"
```

具体路径以控制台「接入配置」为准；字段说明见 PyPI 格式。

## 3. 安装：pip.conf / index-url

默认口径：**安装走 GROUP**（`pypi-all/simple/`），**上传走 HOSTED**。

```ini
# ~/.config/pip/pip.conf 或项目旁 pip.conf
[global]
index-url = http://repo.example.com/pypi/pypi-all/simple/
trusted-host = repo.example.com
```

单次命令：

```bash
pip install some-pkg \
  --index-url "http://$REPO_HOST/pypi/pypi-all/simple/" \
  --trusted-host "$REPO_HOST"
```

只想装内部包、公共包仍走官方源时：

```bash
pip install your-package \
  --index-url https://pypi.org/simple \
  --extra-index-url "http://$REPO_HOST/pypi/pypi-hosted/simple/" \
  --trusted-host "$REPO_HOST"
```

`index-url` / `extra-index-url` 必须以 `/simple/` 结尾。

## 4. 发布：.pypirc 与 twine

`username` **固定写 `__token__`**，不是登录名；`password` 才是访问令牌。

```ini
# ~/.pypirc（勿提交含真实令牌的文件）
[distutils]
index-servers =
  angusrepo

[angusrepo]
repository = http://repo.example.com/pypi/pypi-hosted/
username = __token__
password = your_access_token
```

```bash
python3 -m pip install build twine
python3 -m build
twine upload \
  --repository-url "http://$REPO_HOST/pypi/pypi-hosted/" \
  --username __token__ \
  --password "$REPO_TOKEN" \
  dist/*
```

或 `twine upload -r angusrepo dist/*`。同版本重复上传通常会失败——升版本，不要覆盖。

## 5. 验证闭环（最小可上传包）

```bash
mkdir -p /tmp/angus-pypi-demo && cd /tmp/angus-pypi-demo
cat > pyproject.toml <<'EOF'
[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"

[project]
name = "angus-demo-utils"
version = "1.0.0"
description = "AngusRepo PyPI smoke package"
requires-python = ">=3.9"
EOF
mkdir -p angus_demo_utils
echo 'OK = True' > angus_demo_utils/__init__.py

python3 -m pip install -q build twine
python3 -m build
twine upload \
  --repository-url "http://$REPO_HOST/pypi/pypi-hosted/" \
  --username __token__ \
  --password "$REPO_TOKEN" \
  dist/*
```

干净环境安装：

```bash
python3 -m venv /tmp/angus-pypi-venv && source /tmp/angus-pypi-venv/bin/activate
pip install angus-demo-utils==1.0.0 \
  --index-url "http://$REPO_HOST/pypi/pypi-all/simple/" \
  --trusted-host "$REPO_HOST"
python -c "import angus_demo_utils; print(angus_demo_utils.OK)"
```

应打印 `True`。控制台制品列表应能看到 `1.0.0`。

### CI 最小片段

```yaml
- run: |
    python -m pip install build twine
    python -m build
    twine upload \
      --repository-url "http://$REPO_HOST/pypi/pypi-hosted/" \
      --username __token__ \
      --password "$REPO_TOKEN" \
      dist/*
```

Poetry：`poetry source add` 指 GROUP 的 `/simple/`，认证用户名同样 `__token__`。流水线编排另见 Jenkins 构建测试发布。

## 6. 日常维护

**清理旧版本** — HOSTED 保留最近 N 版，先 Dry Run，见 清理策略。  
**PROXY 冷缓存** — 首次拉公共包会慢，可预热。  
**入库检查** — 轻量门禁在 Repo；深度扫描另接，见 入库门禁与 SBOM。

## 报错速查

| 症状 | 常见原因 | 怎么处理 |
| --- | --- | --- |
| twine 401 | username 不是 `__token__`，或令牌错误 | 改用户名与令牌；查 HOSTED Write |
| `No matching distribution found` | 安装 URL 缺 `/simple/`，或指错仓 | 用 `…/pypi-all/simple/` |
| 能上传不能安装 | 装到了官方源，没走含 HOSTED 的 GROUP | 改 index-url |
| SSL / 证书错误（HTTP） | 未设 `trusted-host` | pip.conf 加上主机名 |
| 409 / 文件已存在 | 同版本重复上传 | 升版本号 |

## FAQ

### 能不能 twine 到 GROUP？

不能。上传只能 HOSTED；pip 安装用 GROUP 的 `/simple/`。

### username 能写登录名吗？

按 PyPI token 约定应写 `__token__`。写登录名在多数私服会直接 401。

### HTTP 环境必须配 trusted-host 吗？

是。无证书时 pip 默认校验 TLS；HTTP 私服不配往往会握手失败。

## 小结

- 安装并打开控制台 → HOSTED + PROXY + GROUP → 发令牌。
- 上传走 HOSTED 根路径；安装走 GROUP `/simple/`。
- `__token__` + 令牌进密码位；用最小包跑通 build → twine → pip。

## 参考文章

- [第一次跑通](https://www.anguskit.com/zh/docs/repo/get-started/quickstart)
- [安装与部署](https://www.anguskit.com/zh/docs/repo/manual/02-installation)
- [PyPI 格式](https://www.anguskit.com/zh/docs/repo/manual/05-formats/04-pypi)
- [清理策略](https://www.anguskit.com/zh/docs/repo/manual/10-cleanup)
- [Jenkins 构建测试发布](https://www.anguskit.com/zh/blog/jenkins-pipeline-build-test-publish-artifacts)
- [入库门禁与 SBOM](https://www.anguskit.com/zh/blog/supply-chain-gate-sbom)

twine upload 报 401，或 pip install 提示 No matching distribution found——多半不是包坏了，而是私服还没接对：服务没起来、上传地址和安装索引搞混、username 没写成 __token__，或 index-url 漏了 /simple/。

PyPI 私有源怎么用：从安装到 twine 上传和 pip 安装

私有化部署后接 PyPI：建 HOSTED/PROXY/GROUP，配 .pypirc 与 pip.conf，用最小包跑通 twine/pip，并处理 401 与 No matching distribution。

人工智能

解决twineupload报401或pip安装失败问题，核心是正确配置AngusRepo私有化部署。步骤包括：安装环境、创建HOSTED/PROXY/GROUP仓库、配置`.pypirc`与`pip.conf`，上传用`__token__`认证至HOSTED根路径，安装走GROUP的`/simple/`索引。通过最小包验证完整流程，确保命令路径和索引URL无误。

代码解释

Windows

Python

MySQL

热销域名限时优惠，新客首年免费！


domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

解决twineupload报401或pip安装失败问题，核心是正确配置AngusRepo私有化部署。步骤包括：安装环境、创建HOSTED/PROXY/GROUP仓库、配置`.pypirc`与`pip.conf`，上传用`__token__`认证至HOSTED根路径，安装走GROUP的`/simple/`索引。通过最小包...

PyPI 私有源怎么用：从安装到 twine 上传和 pip 安装-腾讯云开发者社区-腾讯云

PyPI 私有源怎么用：从安装到 twine 上传和 pip 安装

PyPI 私有源怎么用：从安装到 twine 上传和 pip 安装

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐