singlespa/import-map-deployer

import-map-deployer

镜像概述和主要用途

import-map-deployer是一个后端服务，用于更新https://github.com/WICG/import-maps#installation%E3%80%82%E4%BD%BF%E7%94%A8%E8%AF%A5%E6%9C%8D%E5%8A%A1%E6%97%B6%EF%BC%8C%E5%89%8D%E7%AB%AF%E9%83%A8%E7%BD%B2%E9%80%9A%E8%BF%87%E4%B8%A4%E6%AD%A5%E5%AE%8C%E6%88%90%EF%BC%9A

1. 将JavaScript文件上传到静态服务器或CDN（如AWS S3、Azure Storage、Digital Ocean Spaces等）；
2. 发送HTTP请求（如通过curl或httpie）修改现有import map，指向新上传的文件。

这两步通常在CI流程中执行，以实现前端代码的自动化部署。该服务核心价值在于解决多CI流水线并发部署时的import map覆盖问题，避免传统"拉取-修改-重新上传"流程中的竞态条件。

!import-map-deployer演示

核心功能和特性

并发安全处理

• 解决多CI流水线同时修改import map的竞态条件，确保部署操作原子性，避免后上传覆盖先上传的部署内容。

多存储服务支持

• 兼容AWS S3、Digital Ocean Spaces、Azure Storage、Google Cloud Storage及本地文件系统等多种存储后端。

安全机制

• 支持HTTP基本认证，通过用户名/密码控制访问权限。
• 提供urlSafeList配置项，限制仅允许信任的URL前缀或自定义函数验证的URL被添加到import map。

灵活配置

• 支持JSON或JavaScript配置文件，后者可自定义readManifest和writeManifest函数实现个性化读写逻辑。
• 可配置多环境（locations）管理，如default、prod、test等不同环境的import map。

完整API端点

• 提供健康检查、环境列表查询、import map读写、服务增删等RESTful API端点。

使用场景和适用范围

• 前端微服务部署：管理多个前端微应用的import map，支持独立部署各微应用。
• CI/CD自动化流程：集成到GitLab CI、GitHub Actions等CI工具，实现前端部署自动化。
• 多环境管理：为开发、测试、生产等不同环境维护独立的import map配置。
• 高并发部署场景：当多个团队或项目同时部署前端资源时，确保import map修改的安全性。

安装和使用方法

Docker安装

import-map-deployer已发布到DockerHub，镜像名为https://hub.docker.com/repository/docker/singlespa/import-map-deployer%E3%80%82

Dockerfile示例

dockerfile
FROM singlespa/import-map-deployer:<version-tag>

ENV HTTP_USERNAME=your-username HTTP_PASSWORD=your-password

COPY conf.js /www/

CMD ["yarn", "start", "conf.js"]

docker-compose示例

从项目根目录运行docker-compose up，需确保当前目录存在config.json配置文件：

yaml
version: '3'
services:
  import-map-deployer:
    image: singlespa/import-map-deployer:<version-tag>
    ports:
      - "5000:5000"
    volumes:
      - ./config.json:/www/config.json
    environment:
      - HTTP_USERNAME=admin
      - HTTP_PASSWORD=secure-password

Node安装

通过npm安装并运行：

bash
# 直接运行
npx import-map-deployer config.json

# 自定义端口（默认5000）
PORT=8080 npx import-map-deployer config.json

配置文件详解

配置文件用于设置认证信息、存储方式、URL安全策略等，支持JSON或JavaScript格式（.json或.js）。

核心配置参数

JSON配置示例

json
{
  "urlSafeList": ["https://unpkg.com/", "https://my-cdn.com/"],
  "username": "admin",
  "password": "secure-pass",
  "manifestFormat": "importmap",
  "locations": {
    "default": "s3://my-default-bucket/import-map.json",
    "prod": "s3://my-prod-bucket/import-map.json",
    "test": "file://./test-import-map.json"
  },
  "s3Endpoint": "https://nyc3.digitaloceanspaces.com",
  "cacheControl": "public, max-age=300"
}

JavaScript配置示例（支持自定义函数）

javascript
module.exports = {
  urlSafeList: [
    "https://my-cdn.com/",
    (url) => url.hostname.endsWith(".trusted-domain.com")
  ],
  username: "admin",
  password: process.env.IMD_PASSWORD,
  manifestFormat: "importmap",
  locations: {
    "custom-env": "custom://path"
  },
  // 自定义读取函数
  readManifest: async (env) => {
    const response = await fetch(`https://custom-storage/${env}/import-map.json`);
    return response.text();
  },
  // 自定义写入函数
  writeManifest: async (importMapStr, env) => {
    await fetch(`https://custom-storage/${env}/import-map.json`, {
      method: "PUT",
      body: importMapStr
    });
    return JSON.parse(importMapStr);
  }
};

内置IO方法

AWS S3

通过s3://前缀指定S3存储路径，格式为s3://bucket-name/file.json。依赖AWS CLI环境变量（如AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY）进行认证。

配置示例：

json
{
  "manifestFormat": "importmap",
  "locations": {
    "prod": "s3://my-cdn-bucket/import-map.json"
  },
  "s3": {
    "putObject": { "ACL": "public-read" }
  }
}

Digital Ocean Spaces

通过spaces://前缀指定，格式为spaces://bucket-name.region.digitaloceanspaces.com/file.json。需配置s3Endpoint指向Spaces区域端点。

配置示例：

json
{
  "manifestFormat": "importmap",
  "s3Endpoint": "https://nyc3.digitaloceanspaces.com",
  "locations": {
    "staging": "spaces://my-spaces-bucket.nyc3.digitaloceanspaces.com/import-map.json"
  }
}

Azure Storage

通过对象形式配置，需设置azureContainer、azureBlob，认证通过环境变量AZURE_STORAGE_CONNECTION_STRING或配置中的azureConnectionString。

配置示例：

javascript
module.exports = {
  manifestFormat: "importmap",
  locations: {
    "azure-env": {
      azureContainer: "my-container",
      azureBlob: "import-map.json",
      azureConnectionString: process.env.AZURE_CONN_STR
    }
  }
};

Google Cloud Storage

通过gs://前缀指定，格式为gs://bucket-name/file.json。需设置环境变量GOOGLE_APPLICATION_CREDENTIALS指向密钥文件。

配置示例：

json
{
  "manifestFormat": "importmap",
  "locations": {
    "gcs-env": "gs://my-gcs-bucket/import-map.json"
  }
}

文件系统

直接指定本地文件路径，如./prod-import-map.json。

配置示例：

json
{
  "manifestFormat": "importmap",
  "locations": {
    "local": "./local-import-map.json"
  }
}

API端点

健康检查

• GET /health 或 GET /：返回HTTP 200，文本响应"OK"。

环境列表

• GET /environments：获取所有配置的环境信息。

示例（curl）：

bash
curl -u admin:secure-pass localhost:5000/environments

响应：

json
{
  "environments": [
    { "name": "default", "aliases": [], "isDefault": true },
    { "name": "prod", "aliases": [], "isDefault": false }
  ]
}

获取Import Map

• GET /import-map.json?env=prod：获取指定环境的import map。

示例：

bash
curl -u admin:secure-pass "localhost:5000/import-map.json?env=prod"

更新Import Map

• PATCH /import-map.json?env=prod：合并请求体中的import map到现有配置。

示例（HTTPie）：

bash
http -a admin:secure-pass PATCH :5000/import-map.json?env=prod < new-import-map.json

更新服务

• PATCH /services?env=stage：添加或更新单个服务。

请求体：

json
{ "service": "my-app", "url": "https://my-cdn.com/my-app-v2.js" }

示例（curl）：

bash
curl -u admin:secure-pass -X PATCH -H "Content-Type: application/json" -d '{"service":"my-app","url":"https://my-cdn.com/my-app-v2.js"}' "localhost:5000/services?env=stage"

删除服务

• DELETE /services/{SERVICE_NAME}?env=alpha：删除指定服务。

示例（含特殊字符，需URI编码）：

bash
# 删除服务"@company/my-app"（编码后为"%40company%2Fmy-app"）
curl -u admin:secure-pass -X DELETE "localhost:5000/services/%40company%2Fmy-app?env=alpha"

安全建议

1. 网络隔离：仅在VPC内部暴露import-map-deployer服务，避免公网访问。
2. CI访问控制：确保CI runner位于VPC内或通过隧道访问服务。
3. 强制认证：必须配置username和password启用HTTP基本认证，且凭证仅CI runner知晓。
4. URL安全列表：务必配置urlSafeList限制信任的URL前缀，防止***URL注入。
5. 最小权限：存储服务（如S3）访问凭证仅授予import-map-deployer必要的读写权限。