{"id":30700782,"url":"https://github.com/helloxz/zmirror","last_synced_at":"2026-02-12T05:33:01.526Z","repository":{"id":309007223,"uuid":"1034779034","full_name":"helloxz/zmirror","owner":"helloxz","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-11T07:15:43.000Z","size":1519,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-02T12:53:00.441Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/helloxz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-09T01:14:09.000Z","updated_at":"2025-08-20T13:55:18.000Z","dependencies_parsed_at":"2025-08-09T08:35:38.526Z","dependency_job_id":"2f62bede-396f-470b-84d0-acc132f41403","html_url":"https://github.com/helloxz/zmirror","commit_stats":null,"previous_names":["helloxz/zmirror"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/helloxz/zmirror","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helloxz%2Fzmirror","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helloxz%2Fzmirror/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helloxz%2Fzmirror/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helloxz%2Fzmirror/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/helloxz","download_url":"https://codeload.github.com/helloxz/zmirror/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helloxz%2Fzmirror/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29359503,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T01:03:07.613Z","status":"online","status_checked_at":"2026-02-12T02:00:06.911Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-02T12:52:05.201Z","updated_at":"2026-02-12T05:33:01.513Z","avatar_url":"https://github.com/helloxz.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docker镜像代理系统 (ZMirror)\n\n此项目代码大部分由AI生成，目前存在BUG无法按照要求逻辑运行，只能作为私有Docker镜像运行，目前已经放弃！！！请勿使用！！！\n\n## 功能特性\n\n- ✅ **完全兼容** Docker Registry V2 API\n- 🚀 **多源代理** 支持多个上游镜像源，按优先级自动切换\n- 🔐 **访问控制** 基于白名单的镜像访问控制\n- 👤 **用户管理** 支持管理员和普通用户两种角色\n- 🎯 **现代化WEB界面** Vue3 + Element Plus，支持响应式设计和管理员退出\n- 📊 **访问日志** 完整的访问日志记录和查询\n- ⚡ **高性能** 基于Gin框架，SQLite数据库，WAL模式\n- 🐳 **容器化** 完整的Docker部署支持\n\n## 快速开始\n\n### 方式一：直接运行\n\n```bash\n# 克隆项目\ngit clone \u003crepository-url\u003e\ncd zmirror\n\n# 构建并运行\nmake run\n```\n\n### 方式二：Docker运行\n\n```bash\n# 使用Docker Compose\ndocker-compose up -d\n\n# 或者直接使用Docker\ndocker run -d \\\n  -p 8080:8080 \\\n  -v ./data:/app/data \\\n  --name zmirror \\\n  zmirror:latest\n```\n\n### 首次启动\n\n1. 服务启动后会自动创建 `./data` 目录\n2. 生成默认配置文件 `./data/config.toml`\n3. 创建SQLite数据库 `./data/registry.db`\n4. 创建默认管理员账户：`admin/admin123`\n\n## 配置说明\n\n配置文件位置：`./data/config.toml`\n\n```toml\n[server]\nhost = \"0.0.0.0\"\nport = \"8080\"\n\n[admin]\nusername = \"admin\"\npassword = \"admin123\"\n\n[database]\npath = \"./data/registry.db\"\n```\n\n## 使用方式\n\n### 1. 管理界面\n\n访问 `http://localhost:8080` 进入WEB管理界面\n\n**默认管理员账户：**\n- 用户名：`admin`\n- 密码：`admin123`\n\n### 2. Docker客户端配置\n\n```bash\n# 配置Docker客户端使用代理\n# 方式一：直接指定代理地址\ndocker pull localhost:8080/library/nginx:latest\n\n# 方式二：配置daemon.json（推荐）\n# 编辑 /etc/docker/daemon.json\n{\n  \"registry-mirrors\": [\n    \"http://localhost:8080\"\n  ]\n}\n\n# 重启Docker服务\nsudo systemctl restart docker\n```\n\n### 3. 用户认证\n\n```bash\n# 登录到代理服务\ndocker login localhost:8080\n\n# 输入普通用户的用户名和密码\n# 注意：管理员账户不能用于docker login\n```\n\n## 访问控制机制\n\n### 白名单规则\n\n- **匹配白名单**：允许匿名拉取镜像\n- **未匹配白名单**：需要用户认证后才能拉取\n\n示例：\n```\n白名单前缀：helloz\n匹配镜像：helloz/nginx, helloz/redis 等\n效果：无需认证即可拉取\n```\n\n### 用户类型\n\n**重要说明：管理员和普通用户的存储方式不同！**\n\n#### 1. 管理员用户\n- **存储位置**：配置文件 `data/config.toml`\n- **用途**：只能通过WEB界面登录管理系统\n- **权限**：可以管理镜像源、白名单、普通用户、查看日志\n- **限制**：不能用于 `docker login` 认证\n- **配置示例**：\n  ```toml\n  [admin]\n  username = \"admin\"\n  password = \"your-secure-password\"\n  ```\n\n#### 2. 普通用户\n- **存储位置**：SQLite数据库 `data/registry.db`\n- **用途**：只能用于 `docker login` 认证拉取镜像\n- **权限**：只能拉取镜像，无法访问管理界面\n- **创建方式**：通过WEB管理界面添加\n- **密码存储**：MD5哈希加密存储\n\n## CDN缓存配置\n\n### 推荐缓存的API路径\n\n以下路径建议配置CDN缓存：\n\n#### 长期缓存 (1年)\n```\n/v2/*/blobs/*\n```\n这些是不可变的blob数据，可以长期缓存。\n\n#### 短期缓存 (5分钟)\n```\n/v2/*/manifests/*\n```\nManifest文件可能会更新，建议短期缓存。\n\n### 不应缓存的路径\n```\n/v2/\n/v2/*/tags/list\n/api/*\n/static/*\n```\n\n### Nginx配置示例\n\n```nginx\nserver {\n    listen 80;\n    server_name your-registry.example.com;\n    \n    location / {\n        proxy_pass http://zmirror:8080;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n    }\n    \n    # 长期缓存 blob 数据\n    location ~ ^/v2/.*/blobs/ {\n        proxy_pass http://zmirror:8080;\n        proxy_cache_valid 200 1y;\n        proxy_cache_key $uri;\n        add_header X-Cache-Status $upstream_cache_status;\n    }\n    \n    # 短期缓存 manifest 数据\n    location ~ ^/v2/.*/manifests/ {\n        proxy_pass http://zmirror:8080;\n        proxy_cache_valid 200 5m;\n        proxy_cache_key $uri;\n        add_header X-Cache-Status $upstream_cache_status;\n    }\n}\n```\n\n## API文档\n\n### Docker Registry V2 API\n\n完全兼容Docker Registry V2 API规范：\n\n- `GET /v2/` - API版本检查\n- `GET /v2/{name}/tags/list` - 列出标签\n- `GET /v2/{name}/manifests/{reference}` - 获取manifest\n- `GET /v2/{name}/blobs/{digest}` - 获取blob数据\n\n### 管理API\n\n需要管理员认证，基于HTTP Basic Auth：\n\n#### 镜像源管理\n- `GET /api/registries` - 获取所有镜像源\n- `POST /api/registries` - 创建镜像源\n- `PUT /api/registries` - 更新镜像源\n- `DELETE /api/registries/{id}` - 删除镜像源\n\n#### 白名单管理\n- `GET /api/whitelists` - 获取所有白名单\n- `POST /api/whitelists` - 创建白名单\n- `DELETE /api/whitelists/{id}` - 删除白名单\n\n#### 用户管理\n- `GET /api/users` - 获取所有用户\n- `POST /api/users` - 创建用户\n- `DELETE /api/users/{id}` - 删除用户\n\n#### 访问日志\n- `GET /api/logs` - 获取访问日志\n- `DELETE /api/logs` - 清空访问日志\n\n## 开发说明\n\n### 目录结构\n\n```\nzmirror/\n├── cmd/\n│   └── main.go              # 应用入口\n├── internal/\n│   ├── model/               # 数据模型\n│   ├── service/             # 业务逻辑\n│   ├── handler/             # HTTP处理器\n│   └── middleware/          # 中间件\n├── web/\n│   └── index.html           # WEB管理界面\n├── docs/                    # 文档\n├── data/                    # 数据目录（运行时生成）\n│   ├── config.toml         # 配置文件\n│   └── registry.db         # SQLite数据库\n├── Dockerfile\n├── docker-compose.yml\n├── Makefile\n└── README.md\n```\n\n### 构建命令\n\n```bash\n# 安装依赖\nmake deps\n\n# 开发模式运行\nmake dev\n\n# 构建应用\nmake build\n\n# 构建发布版本\nmake build-release\n\n# 运行测试\nmake test\n\n# 代码格式化\nmake fmt\n```\n\n### 数据库模型\n\n主要数据表：\n\n1. **users** - 用户表\n2. **registries** - 镜像源表\n3. **whitelists** - 白名单表\n4. **access_logs** - 访问日志表\n\n## 部署建议\n\n### 生产环境配置\n\n1. **修改默认密码**\n   ```toml\n   [admin]\n   username = \"admin\"\n   password = \"your-secure-password\"\n   ```\n\n2. **配置反向代理**\n   - 使用Nginx或其他反向代理\n   - 配置SSL/TLS证书\n   - 启用缓存策略\n\n3. **数据备份**\n   - 定期备份 `./data` 目录\n   - 特别是 `registry.db` 数据库文件\n\n4. **监控和日志**\n   - 配置容器日志收集\n   - 监控服务健康状态\n   - 设置告警机制\n\n### Docker Compose配置\n\n```yaml\nversion: '3.8'\n\nservices:\n  zmirror:\n    image: zmirror:latest\n    ports:\n      - \"8080:8080\"\n    volumes:\n      - ./data:/app/data\n    environment:\n      - TZ=Asia/Shanghai\n    restart: unless-stopped\n    healthcheck:\n      test: [\"CMD\", \"wget\", \"--spider\", \"http://localhost:8080/v2/\"]\n      interval: 30s\n      timeout: 5s\n      retries: 3\n```\n\n## 故障排除\n\n### 常见问题\n\n1. **无法连接上游镜像源**\n   - 检查网络连接\n   - 验证镜像源URL配置\n   - 查看服务日志\n\n2. **认证失败**\n   - 确认用户名密码正确\n   - 检查用户类型（管理员不能用于docker login）\n   - 验证密码是否已修改\n\n3. **缓存问题**\n   - 清理Docker客户端缓存\n   - 重启Docker daemon\n   - 检查CDN缓存配置\n\n### 日志查看\n\n```bash\n# Docker容器日志\ndocker logs zmirror\n\n# 应用访问日志\n# 可通过WEB界面查看，或直接查询数据库\n```\n\n## 许可证\n\n本项目采用MIT许可证，详见LICENSE文件。\n\n## 贡献\n\n欢迎提交Issue和Pull Request来改进本项目。\n\n## 更新日志\n\n### v1.0.0\n- 初始版本发布\n- 支持Docker Registry V2 API\n- 实现多源代理和访问控制\n- 提供WEB管理界面\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhelloxz%2Fzmirror","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhelloxz%2Fzmirror","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhelloxz%2Fzmirror/lists"}