# DockerRegMgr

**Repository Path**: EnIaoHao/docker-reg-mgr

## Basic Information

- **Project Name**: DockerRegMgr
- **Description**: DockerRegMgr是一个专注于Docker注册表管理的开源项目，提供便捷的注册表操作、镜像管理和安全控制功能，助力开发者高效管理容器镜像。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-19
- **Last Updated**: 2025-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Docker 私有仓库管理系统

## 项目简介

Docker 私有仓库管理系统是一个企业级 Web 应用，专为简化 Docker 私有仓库的管理而设计。该系统提供了直观的用户界面，支持镜像的全生命周期管理，包括镜像列表查看、标签管理、镜像推送和删除等核心功能。

系统采用前后端分离架构，前端基于原生 HTML/CSS/JavaScript 开发，后端由 Python 动态代理服务器和 Node.js 推送服务器组成，支持多种部署方式，适合从小型团队到大型企业的各种规模和场景使用。

### 核心价值

- 简化 Docker 私有仓库的管理复杂度
- 提供安全可靠的镜像管理解决方案
- 支持大规模镜像的高效处理
- 降低团队使用 Docker 私有仓库的学习成本
- 提供企业级的安全和监控能力

### 功能亮点

- **完整的镜像管理**：支持镜像列表查看、标签管理、镜像推送和删除
- **多种部署方式**：支持 Docker Compose 部署、脚本部署和手动部署
- **安全认证机制**：基于角色的身份认证（RBAC），支持管理员、普通用户和只读用户
- **优化的性能体验**：支持大量镜像的高效处理，包含缓存机制和虚拟滚动
- **完善的监控机制**：提供健康检查和监控指标端点
- **企业级功能**：支持审计日志、备份恢复和垃圾回收
- **安全配置**：包含 CORS 限制、安全头设置和 HTTPS 支持
- **跨平台兼容**：支持 Windows、Linux 和 macOS 环境
- **直观的用户界面**：简洁易用的 Web 界面，降低操作复杂度

### 技术栈

- **前端**：HTML5, CSS3, JavaScript (ES6+)
- **后端**：Python 3.7+, Node.js 14+
- **代理服务**：Flask 框架
- **容器化**：Docker, Docker Compose
- **Web 服务器**：Nginx
- **身份认证**：JWT 令牌机制

### 目标用户

- 开发团队和 DevOps 工程师
- 需要管理大量 Docker 镜像的企业
- 希望简化私有仓库管理的 IT 管理员
- 寻求安全可靠的镜像管理解决方案的组织

## 项目结构

```
docker-images-registry/
├── config/                  # 配置文件目录
│   ├── config.json          # 主配置文件
│   ├── nginx.conf           # Nginx 配置文件
│   └── registry-config.yml  # Docker Registry 配置示例
├── docs/                    # 文档目录
│   ├── gc.md                # 垃圾回收说明
│   └── optimization-plan.md # 优化计划
├── logs/                    # 日志文件目录
├── scripts/                 # 脚本目录
│   ├── gc-clean-orphans-in-repo.sh  # 垃圾回收脚本
│   ├── registry-backup-restore.sh   # 备份恢复脚本
│   ├── start-all.ps1            # 启动脚本（带彩色输出）
│   ├── start-all-simple.ps1     # 启动脚本（简单版本）
│   └── start-all-fix.ps1        # 启动脚本（纯英文修复版本）
├── src/                     # 源代码目录
│   ├── frontend/            # 前端代码
│   │   ├── app.js           # 前端应用逻辑
│   │   ├── index.html       # 前端主页面
│   │   └── login.html       # 登录页面
│   └── backend/             # 后端代码
│       ├── node/            # Node.js 后端
│       │   ├── push-image.js      # 推送镜像脚本
│       │   └── push-server.js     # 推送服务器
│       └── python/          # Python 后端
│           ├── dynamic-proxy.py   # 动态代理服务器
│           └── simple-proxy.py    # 简单代理服务器
├── .gitignore               # Git 忽略文件
├── cors-test.html           # CORS 测试页面
├── docker-compose.yml       # Docker Compose 配置
├── package-lock.json        # Node.js 依赖锁定文件
├── package.json             # Node.js 项目配置
└── README.md                # 项目说明文档
```

## 配置文件说明

### config/config.json

配置文件 `config/config.json` 包含了 Docker 私有仓库管理系统的所有配置信息，集中管理 IP 和端口等关键参数。

```json
{
    "docker": {
        "registry": {
            "internal": "192.168.1.200:5000",  // 内网 Docker 仓库地址
            "external": "120.237.152.218:5000", // 外网 Docker 仓库地址
            "default": "192.168.1.200:5000"     // 默认 Docker 仓库地址
        }
    },
    "servers": {
        "http": {
            "port": 5001                          // HTTP 服务器端口
        },
        "proxy": {
            "port": 5002,                         // 代理服务器端口
            "default": "192.168.1.200:5000"      // 代理服务器默认目标地址
        },
        "push": {
            "port": 5003                          // 推送服务器端口
        }
    }
}
```

## 配置项详细说明

### Docker 仓库配置

| 配置项 | 说明 |
|--------|------|
| `internal` | 内网 Docker 仓库地址，用于内部网络访问 |
| `external` | 外网 Docker 仓库地址，用于外部网络访问 |
| `default` | 默认 Docker 仓库地址，当没有指定仓库地址时使用 |

### 服务器配置

| 配置项 | 说明 |
|--------|------|
| `http.port` | HTTP 服务器端口，用于提供静态文件服务 |
| `proxy.port` | 代理服务器端口，用于处理 CORS 问题 |
| `proxy.default` | 代理服务器默认目标地址，当没有指定目标地址时使用 |
| `push.port` | 推送服务器端口，用于执行 Docker 命令推送镜像 |

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 启动服务

#### 方式一：使用 Docker Compose 部署（推荐）

**启动服务：**

```bash
docker-compose up -d
```

**检查服务状态：**

```bash
docker-compose ps
```

**停止服务：**

```bash
docker-compose down
```

**服务端口：**
- 前端应用：`8081`
- Docker Registry：`5000`
- 动态代理服务：`5002`
- 推送服务器服务：`5003`

#### 方式二：使用启动脚本

提供了三个启动脚本，根据环境选择合适的版本：

| 脚本名称 | 特点 | 适用场景 |
|----------|------|----------|
| `start-all.ps1` | 带彩色输出和 emoji | 支持彩色显示的 PowerShell 环境 |
| `start-all-simple.ps1` | 纯文本输出，自动创建日志目录 | 所有 PowerShell 环境 |
| `start-all-fix.ps1` | 纯英文输出，无编码问题 | 所有 PowerShell 环境，尤其是中文环境有编码问题时 |

**执行命令：**

```powershell
# 选择其中一个执行
.\scripts\start-all.ps1          # 带彩色输出
.\scripts\start-all-simple.ps1   # 简单文本输出
.\scripts\start-all-fix.ps1      # 纯英文修复版本
```

**注意：** 如果遇到执行权限问题，使用以下命令：

```powershell
powershell.exe -ExecutionPolicy Bypass -File .\scripts\start-all-fix.ps1
```

#### 方式三：手动启动

1. **启动 HTTP 服务器**

```bash
python -m http.server 5001 --directory src/frontend
```

2. **启动动态代理服务器**

```bash
python src/backend/python/dynamic-proxy.py 5002
```

3. **启动推送服务器**

```bash
node src/backend/node/push-server.js
```

### 3. 访问应用

| 部署方式 | 访问地址 |
|----------|----------|
| Docker Compose | http://localhost:8081 |
| 脚本/手动启动 | http://localhost:5001 |

### 4. 登录系统

使用以下默认账号登录：

| 用户名 | 密码 | 角色 | 权限 |
|--------|------|------|------|
| `admin` | `admin123` | 管理员 | 全部功能 |
| `user` | `user123` | 普通用户 | 查看、推送、刷新 |
| `readonly` | `readonly123` | 只读用户 | 查看、刷新 |

## 安全功能

### 1. 身份认证与权限控制

- **基于角色的访问控制（RBAC）**：支持三种角色
- **JWT 令牌**：登录后生成令牌，用于 API 认证
- **会话管理**：支持记住我功能和会话超时

### 2. CORS 配置

- 限制允许的域名列表
- 支持多种 CORS 头配置
- 配置文件：`src/backend/python/dynamic-proxy.py`

### 3. HTTPS 支持

- 动态代理服务器支持 HTTPS
- 可通过命令行参数指定证书和密钥文件：
  ```bash
  python dynamic-proxy.py 5002 --https --cert cert.pem --key key.pem
  ```

### 4. 安全头设置

前端响应中包含以下安全头：
- `Content-Security-Policy`
- `X-Content-Type-Options`
- `X-Frame-Options`
- `X-XSS-Protection`
- `Strict-Transport-Security`
- `Referrer-Policy`

## 监控与健康检查

### 1. 健康检查端点

- `/health`
- `/healthz`
- `/_health`

### 2. 监控指标端点

- `/metrics`
- `/_metrics`

### 3. 监控指标

- 请求计数
- 响应时间
- 状态码分布
- 错误计数
- 请求路径统计

## 审计日志

### 1. 日志记录范围

- 用户登录/登出
- 仓库连接
- 镜像列表查看
- 镜像推送
- 镜像/标签删除
- 刷新操作

### 2. 日志存储

- 本地存储：使用浏览器的 localStorage
- 日志格式：JSON
- 最大日志条目：1000条

## 备份与恢复

### 1. 备份恢复脚本

项目提供了 `registry-backup-restore.sh` 脚本，用于备份和恢复 Docker Registry 数据：

**创建备份：**
```bash
./scripts/registry-backup-restore.sh backup
```

**恢复备份：**
```bash
./scripts/registry-backup-restore.sh restore --file registry_backup_20250101_120000.tar.gz
```

**列出备份：**
```bash
./scripts/registry-backup-restore.sh list
```

### 2. 备份功能

- 自动停止和启动 Registry 服务
- 支持指定备份目录
- 自动清理旧备份
- 支持指定保留天数

## 性能优化

### 1. 前端优化

- **请求限制**：限制并行请求数量
- **缓存机制**：前端缓存镜像列表
- **渲染优化**：使用文档片段减少 DOM 操作
- **搜索防抖**：延迟搜索请求，避免频繁查询
- **虚拟滚动**：支持大量镜像的高效渲染

### 2. 后端优化

- **请求大小限制**：防止过大请求
- **超时处理**：设置合理的超时时间
- **错误处理**：详细的错误信息和分类
- **监控指标**：实时收集性能数据

## 功能说明

### 1. 连接仓库

在首页输入 Docker 私有仓库地址，点击"连接仓库"按钮即可连接到仓库。

### 2. 查看镜像列表

连接成功后，系统会自动加载仓库中的镜像列表。

### 3. 查看标签

点击镜像名称，可以查看该镜像的所有标签。

### 4. 推送镜像

在"推送镜像"输入框中输入本地镜像名称（如 `redis:alpine`），点击"推送镜像"按钮即可将镜像推送到仓库。

### 5. 删除镜像

点击镜像列表中的"删除"按钮，可以删除整个镜像（包括所有标签）。

### 6. 删除标签

在标签列表中，点击"删除"按钮，可以删除指定的标签。

### 7. 复制拉取命令

在标签列表中，点击"复制内网"或"复制外网"按钮，可以复制对应的镜像拉取命令。

### 8. 查看镜像详情

在标签列表中，点击"详情"按钮，可以查看镜像的详细信息。

## 服务器说明

### HTTP 服务器
- 命令：`python -m http.server 5001`
- 作用：提供静态文件服务，如 index.html、app.js 等
- 端口：配置文件中的 `http.port`
- 日志：`logs/http-server.log`

### 动态代理服务器
- 命令：`python dynamic-proxy.py`
- 作用：处理 CORS 问题，根据请求头动态转发到不同的目标地址
- 支持的目标地址来源：
  - 请求头 `X-Target-Url`
  - 请求头 `X-Target-Registry`（前端使用）
  - 查询参数 `target_url`
- 端口：配置文件中的 `proxy.port`
- 日志：`logs/dynamic-proxy.log`
- 支持的 HTTP 方法：GET, POST, PUT, DELETE, HEAD, OPTIONS

### 推送服务器
- 命令：`node push-server.js`
- 作用：执行 Docker 命令推送镜像
- 端口：配置文件中的 `push.port`
- 日志：`logs/push-server.log`

## 镜像删除机制

### 重要说明

Docker Registry 的镜像删除是一个**两步过程**：

1. **Web 界面删除**：仅删除元数据引用，**不会立即释放磁盘空间**
2. **服务器端垃圾回收（GC）**：删除未被引用的镜像层数据，**真正释放磁盘空间**

### 为什么需要服务器端 GC？

- **分层存储**：Docker Registry 采用分层存储，删除标签/镜像时仅删除引用，实际镜像层仍保留
- **引用计数**：只有当镜像层**没有任何标签引用**时，才能被安全删除
- **权限要求**：GC 操作需要访问 Registry 数据卷，通常需要停止服务才能执行

### 完整删除流程

#### 1. 通过 Web 界面删除

在管理页面执行：
- 删除过期镜像
- 删除不需要的标签

这一步只会删除**元数据引用**，不会释放磁盘空间。

#### 2. 服务器端执行 GC 操作

需要在 Docker Registry 所在服务器上执行以下操作：

##### 方式一：使用项目提供的 GC 脚本（推荐）

```bash
# 1. 复制 gc-clean-orphans-in-repo.sh 到服务器
# 2. 添加执行权限
sudo chmod +x gc-clean-orphans-in-repo.sh
# 3. 修改脚本配置（根据实际情况调整）
#    - REG_URL: Registry 地址
#    - REG_VOLUME: Registry 数据卷名称
#    - REG_NAME: Registry 容器名称
# 4. 执行 GC 清理
./gc-clean-orphans-in-repo.sh [仓库名]  # 仓库名留空=清理所有仓库
```

##### 方式二：手动执行 GC 命令

```bash
# 1. 停止 Registry 服务
docker stop registry

# 2. 执行垃圾回收（--dry-run 可预览要删除的内容）
docker run --rm \
  -v registry_registry-data:/var/lib/registry \
  registry:latest \
  registry garbage-collect /etc/docker/registry/config.yml

# 3. 启动 Registry 服务
docker start registry
```

### GC 脚本功能说明

`gc-clean-orphans-in-repo.sh` 脚本包含以下功能：

1. **干跑模式**：先预览要删除的"孤儿"镜像层，确保安全
2. **自动清理**：停止服务 → 执行 GC → 启动服务
3. **清理空仓库**：自动删除因删除标签而变空的仓库
4. **支持指定仓库**：可只清理特定仓库，不影响其他仓库
5. **错误处理**：包含完善的错误处理机制

### 注意事项

1. **服务中断**：GC 操作会停止 Registry 服务，建议在**低峰期**执行
2. **数据安全**：执行前建议**备份 Registry 数据卷**
3. **定期执行**：建议定期（如每周）执行 GC，避免磁盘空间过度占用
4. **配置检查**：确保 Registry 配置文件中启用了删除功能
5. **权限检查**：确保脚本有执行权限，且当前用户有权限访问 Docker

## 注意事项

1. 所有服务器都必须使用相同的配置文件，确保配置一致
2. 修改配置后，需要重启相关服务器才能生效（除了前端页面）
3. 配置文件中的地址必须是可访问的，否则会导致服务无法正常运行
4. 端口号必须是未被占用的，否则会导致服务器启动失败
5. 推送镜像时，确保本地 Docker 中存在该镜像
6. 确保 `logs` 目录存在，或使用自动创建日志目录的 `start-all-simple.ps1` 或 `start-all-fix.ps1` 脚本

## 故障排查

### 常见问题

1. **服务器启动失败**
   - 检查端口是否被占用：`netstat -ano | findstr :端口号`
   - 检查配置文件是否正确
   - 确保日志目录存在

2. **无法访问仓库**
   - 检查仓库地址是否正确
   - 网络连接是否正常
   - 代理服务器是否正常运行

3. **CORS 错误**
   - 检查代理服务器是否正常运行
   - 确认前端使用了正确的代理地址
   - 检查浏览器控制台的错误信息

4. **推送失败**
   - 检查推送服务器是否正常运行
   - 确保本地 Docker 中存在该镜像
   - 检查 Docker 命令是否正确

5. **脚本执行错误**
   - 中文环境下推荐使用 `start-all-fix.ps1` 纯英文版本
   - 检查 PowerShell 版本是否支持
   - 使用 `powershell.exe -ExecutionPolicy Bypass` 绕过执行策略

### 日志查看

所有服务器的日志都保存在 `logs` 目录下：
- `logs/http-server.log` - HTTP 服务器日志
- `logs/dynamic-proxy.log` - 动态代理服务器日志
- `logs/dynamic-proxy.error.log` - 代理服务器错误日志
- `logs/push-server.log` - 推送服务器日志

## 最佳实践

1. **集中管理**：所有 IP 和端口配置都集中在 `config/config.json` 文件中，便于管理和修改
2. **保留默认值**：在代码中保留默认配置，当配置文件无法读取时使用
3. **合理命名**：配置项命名清晰，便于理解和使用
4. **文档化**：编写详细的配置说明，便于其他开发者使用
5. **定期备份**：定期备份配置文件和重要数据
6. **使用合适的启动脚本**：根据环境选择合适的启动脚本，避免编码问题
7. **定期执行 GC**：每周执行一次垃圾回收，释放磁盘空间
8. **启用 HTTPS**：在生产环境中使用 HTTPS 加密通信
9. **限制 CORS 来源**：仅允许信任的域名访问 API
10. **监控服务状态**：定期检查服务健康状态

## 版本历史

### 1.3.0
- 完善项目文档
- 添加身份认证和权限控制
- 优化 CORS 配置
- 添加 HTTPS 支持
- 增强错误处理机制
- 添加健康检查和监控
- 优化性能，支持大量镜像
- 添加审计日志功能
- 实现备份恢复机制
- 创建容器化部署方案

### 1.2.0
- 修复动态代理服务器的编码问题
- 添加对 `X-Target-Registry` 请求头的支持
- 新增 `start-all-fix.ps1` 纯英文修复版本
- 优化 README 文档，添加详细的故障排查
- 完善镜像删除机制说明，添加 GC 操作指南

### 1.1.0
- 优化项目结构，分离前后端代码
- 添加启动脚本，简化服务启动
- 支持配置文件集中管理

### 1.0.0
- 初始版本，支持基本的镜像管理功能

## 贡献

欢迎提交问题和建议，帮助改进 Docker 私有仓库管理系统。

## 许可证

本项目采用 MIT 许可证。