# registry-proxy

**Repository Path**: johnroot/registry-proxy

## Basic Information

- **Project Name**: registry-proxy
- **Description**: Docker Registry 代理服务
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-25
- **Last Updated**: 2025-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Docker Registry 代理服务

## 项目概述

这是一个用 Go 语言开发的 Docker Registry 代理服务，用于代理和缓存 Docker Hub 的镜像请求，提供更快的镜像拉取速度和更稳定的服务。支持 Docker Registry API v2 规范，完全兼容 Docker 客户端工具。

## 功能特性

- **Docker Registry API v2 兼容**：完全兼容 Docker Registry API v2 规范
- **智能代理**：自动代理请求到 Docker Hub 或其他上游 Registry
- **认证支持**：支持 Docker Hub 的认证机制，包括公有和私有仓库
- **HTTPS 支持**：支持 TLS/SSL 加密连接
- **自动证书管理**：集成 Let's Encrypt 自动证书申请和续期
- **健康检查**：提供健康检查端点 `/health`
- **监控指标**：提供基础监控端点 `/metrics`
- **详细日志**：支持不同级别的日志记录和 JSON 格式输出
- **重试机制**：内置请求重试逻辑，提高服务稳定性
- **CORS 支持**：跨域资源共享支持
- **自动恢复**：异常恢复中间件

## 快速开始

### 使用 Docker 运行

```bash
# 基本运行
docker run -d --name registry-proxy -p 80:80 johnrootok/registry-proxy:latest

# 带环境变量的运行
docker run -d --name registry-proxy \
  -p 80:80 \
  -p 443:443 \
  -e PROXY_HTTPS_ENABLE="false" \
  -e PROXY_LOG_LEVEL="info" \
  -e ENABLE_AUTO_CERT=1 \
  -e CERT_DOMAIN="your-domain.com" \
  -e CERT_EMAIL="your-email@example.com" \
  -e TZ="Asia/Shanghai" \
  -v $(pwd)/certs:/app/certs \
  --restart unless-stopped \
  johnrootok/registry-proxy:latest
```

### 从源码构建运行

```bash
# 克隆项目
git clone <repository-url>
cd registry-proxy

# 构建项目
go build -o registry-proxy .

# 运行服务
./registry-proxy -port 8080 -upstream https://registry-1.docker.io -verbose
```

### 自动证书配置

```bash
# 启用自动申请免费证书
ENABLE_AUTO_CERT=1

# 证书域名
CERT_DOMAIN="your-domain.com"

# 证书邮箱（用于 Let's Encrypt 通知）
CERT_EMAIL="your-email@example.com"
```

## API 端点

### 健康检查

```bash
GET /health
```

响应示例：
```json
{
  "status": "ok",
  "version": "1.0.0",
  "upstream": "https://registry-1.docker.io"
}
```

### 监控指标

```bash
GET /metrics
```

提供基础的监控指标信息。

### Docker Registry API

服务完全支持 Docker Registry API v2 规范：

- `GET /v2/` - 版本检查
- `GET /v2/{name}/manifests/{reference}` - 获取镜像清单
- `GET /v2/{name}/blobs/{digest}` - 获取镜像层数据
- `POST /token` - 认证令牌获取

## 认证支持

### 公有仓库

公有镜像（如 `nginx`, `ubuntu`）无需认证即可访问。

### 私有仓库

私有镜像需要提供认证信息：

```bash
# 使用用户名密码
docker login your-proxy-domain.com

# 使用 Bearer Token
docker login -u "$token" -p "your-token" your-proxy-domain.com
```

## 部署指南

### 生产环境部署

1. **配置 TLS/HTTPS**：
   ```bash
   PROXY_TLS_ENABLED=true
   PROXY_TLS_CERT=/path/to/fullchain.pem
   PROXY_TLS_KEY=/path/to/privkey.pem
   PROXY_HTTPS_PORT=443
   PROXY_REDIRECT_HTTP=true
   ```

2. **启用自动申请免费证书**（推荐）：
   ```bash
   ENABLE_AUTO_CERT=1
   CERT_DOMAIN="your-domain.com"
   CERT_EMAIL="admin@your-domain.com"
   ```

3. **配置日志级别**：
   ```bash
   PROXY_LOG_LEVEL=info  # 生产环境建议使用 error 级别
   ```

4. **设置适当的超时**：
   ```bash
   PROXY_READ_TIMEOUT=30s
   PROXY_WRITE_TIMEOUT=30s
   PROXY_IDLE_TIMEOUT=60s
   ```

### 多架构构建

项目支持多架构构建，可以在 Dockerfile 中配置相应的构建参数。

## 故障排除

### 常见问题

1. **证书问题**：确保证书文件路径正确且权限适当
2. **端口冲突**：检查端口是否被其他服务占用
3. **网络连接**：验证上游 registry 的可访问性
4. **认证失败**：检查认证信息是否正确

### 日志调试

启用详细日志记录来帮助诊断问题：

```bash
PROXY_LOG_LEVEL=debug
```

## 性能优化

### 缓存配置

启用缓存可以显著提高性能：

```bash
PROXY_CACHE_ENABLED=true
PROXY_CACHE_DIR=/path/to/cache
```

### 连接池优化

调整 HTTP 客户端配置以获得更好的性能：

```bash
PROXY_RETRY_COUNT=3
PROXY_RETRY_DELAY=1s
```

## 安全考虑

1. **使用 HTTPS**：在生产环境中始终启用 TLS
2. **定期更新**：保持镜像和依赖项的最新状态
3. **访问控制**：配置适当的网络访问控制
4. **日志监控**：监控日志以检测异常活动

## 贡献指南

欢迎提交 Issue 和 Pull Request 来改进这个项目。

## 许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

## 支持

如果您遇到问题或有疑问，请：

1. 查看本文档
2. 检查项目 Issue
3. 提交新的 Issue