metacpan/metacpan-web

Metacpan本地服务Docker镜像

镜像概述

本Docker镜像用于在本地环境部署Metacpan服务，复刻metacpan.org的核心功能，提供Perl模块的搜索、文档查阅和元数据查询能力。适用于需要离线访问Perl模块资源或在开发环境中集成模块文档服务的场景，无需依赖外部网络即可获取完整的Perl模块信息。

核心功能与特性

• 模块搜索：支持按模块名称、作者、关键词等多维度检索Perl模块
• 文档浏览：提供完整的模块POD文档转HTML展示，支持语法高亮和目录导航
• 元数据查询：获取模块版本、依赖关系、授权信息、发布历史等元数据
• 离线支持：内置基础模块数据，支持完全离线环境下的文档访问和搜索
• 轻量级部署：基于Alpine Linux构建，镜像体积小，启动速度快，资源占用低
• 灵活配置：支持通过环境变量和配置文件自定义服务端口、缓存策略和数据存储路径

使用场景与适用范围

• Perl开发环境：为本地Perl项目提供即时的模块文档查阅工具，提升开发效率
• 离线工作环境：在无网络连接的场景下（如隔离开发环境），仍可访问完整的Perl模块资源
• 企业内部服务：部署私有Metacpan服务，管理内部Perl模块库及文档
• 教学与培训：作为Perl语言学习辅助工具，提供本地化的模块参考资料

使用方法与配置说明

基本部署

通过以下命令快速启动本地Metacpan服务：

bash
docker run -d -p 5000:5000 --name metacpan-local metacpan/local:latest

服务启动后，访问 http://localhost:5000 即可使用Web界面进行模块搜索和文档浏览。

数据持久化配置

为避免容器重启导致模块数据丢失，建议挂载数据卷持久化存储模块缓存：

bash
docker run -d \
  -p 5000:5000 \
  -v metacpan-data:/app/data \
  --name metacpan-local \
  metacpan/local:latest

其中 metacpan-data 为持久化数据卷，自动创建并存储模块缓存和服务配置。

环境变量配置

支持通过环境变量自定义服务行为，常用配置参数如下：

示例：自定义端口和日志级别

bash
docker run -d \
  -p 8080:8080 \
  -e PORT=8080 \
  -e LOG_LEVEL=debug \
  -e CACHE_TTL=604800 \
  --name metacpan-local \
  metacpan/local:latest

Docker Compose配置

通过 docker-compose.yml 实现多容器协同部署（如结合数据库）：

yaml
version: '3.8'
services:
  metacpan:
    image: metacpan/local:latest
    ports:
      - "5000:5000"
    volumes:
      - metacpan-data:/app/data
    environment:
      - OFFLINE_MODE=true
      - CACHE_TTL=604800  # 7天缓存有效期
      - MAX_SEARCH_RESULTS=100
    restart: unless-stopped

volumes:
  metacpan-data:  # 自动创建持久化卷

执行 docker-compose up -d 启动服务，docker-compose logs -f 可查看实时日志。

注意事项

• 首次启动时，服务会自动同步基础模块数据（约需5-10分钟，取决于网络速度）
• 离线模式下如需更新模块数据，可通过 docker exec metacpan-local /app/scripts/update_data.sh 手动触发同步
• 生产环境建议配置反向代理（如Nginx）并启用HTTPS，增强服务安全性
• 支持通过挂载自定义 metacpan_config.json 文件覆盖默认配置：-v ./custom_config.json:/app/config/metacpan_config.json