ld4p/sinopia_api

Sinopia API Docker镜像文档

镜像概述

本Docker镜像提供Sinopia私有npm仓库的API服务，用于快速搭建本地私有npm仓库，实现npm包的全生命周期管理。通过该镜像可便捷部署支持包发布、存储、检索的API接口，满足企业或团队对私有npm包的安全管理需求。

核心功能特性

• 私有包管理：提供完整API接口支持npm包的发布、安装、版本控制及删除操作
• 用户认证与权限：集成用户认证机制，支持基于角色的访问控制，限制包的操作权限
• 上游仓库缓存：自动缓存公共npm仓库（如npmjs.org）的包资源，提升重复下载效率
• 灵活存储配置：支持文件系统、数据库等多种存储后端，可自定义存储路径与容量
• 日志审计：记录包操作日志，支持日志级别配置，便于追踪包管理行为
• 跨平台部署：基于Docker容器化封装，兼容Linux、Windows、macOS等主流操作系统

使用场景

• 企业私有仓库：搭建企业级私有npm仓库，集中管理内部开发的业务组件和工具包
• 团队协作开发：团队内部共享私有包，避免重复开发，规范包版本管理
• 权限隔离环境：需严格控制敏感包访问权限的场景，如商业项目私有依赖管理
• 内网环境适配：在无公网访问的内网环境中提供本地化npm包管理能力

使用方法

基本运行命令

通过以下命令快速启动Sinopia API服务（默认端口4873）：

bash
docker run -d -p 4873:4873 --name sinopia-api sinopia-api:latest

持久化部署

为避免容器重启导致数据丢失，建议挂载本地目录持久化存储配置与包数据：

bash
docker run -d -p 4873:4873 \
  -v /host/path/storage:/app/storage \
  -v /host/path/config:/app/config \
  -v /host/path/logs:/app/logs \
  --name sinopia-api sinopia-api:latest

环境变量配置

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

配置文件说明

核心配置通过挂载的config.yaml文件调整，关键配置项示例：

yaml
# 存储配置
storage:
  type: file  # 支持file/mongodb等存储类型
  path: ./storage  # 容器内存储路径

# 用户认证配置
auth:
  htpasswd:
    file: ./htpasswd  # 存储用户凭证的文件路径
    max_users: -1  # -1表示不限制用户注册

# 上游仓库配置
uplinks:
  npmjs:
    url: https://registry.npmjs.org/  # 公共npm仓库地址

# 包权限配置
packages:
  '@internal/*':  # 内部作用域包
    access: $authenticated  # 访问需认证
    publish: admin  # 仅管理员可发布
  '*':  # 其他包
    access: $anonymous  # 匿名可访问
    publish: $authenticated  # 认证用户可发布
    proxy: npmjs  # 代理至公共仓库

服务访问与使用

1. 配置npm客户端：

   bash
   npm set registry http://localhost:4873
   

2. 用户注册与登录：

   bash
   npm adduser --registry http://localhost:4873  # 注册用户
   npm login --registry http://localhost:4873     # 用户登录
   

3. 包发布与安装：

   bash
   npm publish  # 发布当前项目包至私有仓库
   npm install <package-name>  # 从私有仓库安装包
   

注意事项

• 生产环境建议通过反向代理（如Nginx）配置HTTPS加密传输
• 定期备份storage目录数据，防止数据丢失
• 根据业务规模调整存储容量配置，避免存储空间不足
• 首次部署需通过npm adduser创建管理员账户，并配置权限策略