uchiru/spa-base

SPA Base 镜像文档

![Docker Repository on Quay]([***]

镜像概述

SPA Base是一个专为JS单页应用(SPA)设计的基础Docker镜像。它基于Nginx构建，提供静态资源服务，并集成了S3资源同步、环境变量模板替换等功能，简化SPA应用的部署流程。

核心功能与特性

• Nginx静态服务：通过Nginx提供/var/www目录下的静态文件
• S3资源同步：启动时自动将静态资源从S3 bucket同步至本地
• 请求代理：当本地未找到JS或CSS文件时，自动将请求代理至S3 bucket
• 环境变量模板替换：支持在JS、CSS、HTML、JSON文件中通过模板语法替换环境变量
• 自定义Nginx配置：允许通过配置文件扩展Nginx服务器配置
• 浏览器版本控制：可配置阻止旧版浏览器访问或提示更新
• 安全增强：支持配置Content Security Policy (CSP)头

使用场景

适用于需要部署JS单页应用的场景，特别是：

• 需要从S3动态同步静态资源的应用
• 需要根据环境动态配置参数的SPA
• 需要控制浏览器兼容性的Web应用
• 需要自定义Nginx配置的前端项目

配置说明

环境变量

必选环境变量

• BASE_PATH：SPA所在的路径，必须以斜杠开头，不以斜杠结尾（如/profile/students）
• APP_NAME：应用名称，用于在S3 bucket中区分不同应用的资源
• S3_ID：S3 bucket的访问ID
• S3_KEY：S3 bucket的访问密钥
• S3_BUCKET：S3 bucket的名称

可选环境变量

• CUSTOM_CONFIG_PATH：自定义Nginx配置文件路径，其内容将被包含在server指令内
• MANDATORY_VARIABLES：必需环境变量列表（换行分隔），缺少这些变量时容器无法启动

  Dockerfile
  ENV MANDATORY_VARIABLES="
  STUDENT_HEADER_PATH
  JWT_AUTH_PATH
  "
  

• USE_SSI：是否启用SSI指令处理，设为true时启用
• CSP_HEADER：Content Security Policy头内容
• CSP_HEADER_PATH：包含CSP头内容的文件路径
• CSP_REPORT_ONLY：是否启用CSP报告模式，设为true时仅报告不阻止

环境变量说明

• BASE_PATH用于指定SPA在域名下的子路径，例如uchi.ru/profile/students对应的BASE_PATH=/profile/students，需与资产编译时配置一致
• APP_NAME用于在S3 bucket中创建独立目录，避免不同应用或环境的资产混合

使用方法

基础使用

该镜像需作为基础镜像使用，在构建阶段复制编译后的静态文件到/var/www目录：

dockerfile
# Dockerfile
FROM node:10.15 as build

# 构建步骤
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM spa-base
COPY --from=build /app/build /var/www

构建并运行容器：

bash
docker build -t app .
docker run --name app -it --rm -p 8080:80 \
         -e BASE_PATH=/profile/students \
         -e APP_NAME=test-1 \
         -e S3_ID=your-s3-id \
         -e S3_KEY=your-s3-key \
         -e S3_BUCKET=uchiru-static-files app <command>

可用命令

• serve（默认）：启动Nginx，以/var/www为根目录提供服务
• upload：将资产上传至S3 bucket（用于前置步骤）
• serve-debug：启动Nginx调试模式

文件模板替换

启动时，JS/CSS/HTML/JSON文件中的模板字符串会通过https://github.com/stephenc/envsub%E6%9B%BF%E6%8D%A2%E4%B8%BA%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E5%80%BC%EF%BC%8C%E6%94%AF%E6%8C%81%E4%BB%A5%E4%B8%8B%E8%AF%AD%E6%B3%95%EF%BC%9A

• <%VAR_NAME%>：替换为环境变量VAR_NAME的值，如变量不存在则保留原字符串
• <%VAR_NAME-%>：替换为环境变量VAR_NAME的值，如变量不存在则替换为空字符串
• <%VAR_NAME-default%>：替换为环境变量VAR_NAME的值，如变量不存在则替换为default

浏览器版本控制

如需限制旧版浏览器访问，可在项目根目录添加browserslist.sh文件，并在Dockerfile中复制：

dockerfile
COPY ./browserslist.sh /browserslist.sh

browserslist.sh示例：

bash
export OUTDATED="
  Chrome <= 58,
  Firefox <= 57,
  Edge <=16,
  Safari <= 10.1,
  ie <= 11,
  ios_saf <= 10.1,
  Opera <= 44"
export NEED_UPDATE="
  Chrome <= 72,
  Firefox <= 68,
  ios_saf <= 11.1.2,
  Edge <=79,
  Safari <= 11.1.2,
  Opera <= 59"

• OUTDATED：完全不支持的浏览器列表，用户将被重定向至https://uchi.ru/lp/old-browser
• NEED_UPDATE：需要更新的浏览器列表，用户将被重定向至包含返回链接的提示页，并设置1个月有效期的old_browser_lover cookie

Nginx高级配置

自定义配置

通过CUSTOM_CONFIG_PATH指定自定义Nginx配置文件，其内容将被包含在server指令内：

dockerfile
# Dockerfile
COPY nginx-custom.conf /var/nginx/
ENV CUSTOM_CONFIG_PATH=/var/nginx/nginx-custom.conf

nginx-custom.conf示例：

nginx
location ^~ /foo/(one|two)/bar/ {
  rewrite ^/foo/(one|two)/(.*)$ /foo/$2;
}

SSI支持

设置USE_SSI=true启用SSI指令处理：

dockerfile
ENV USE_SSI=true

使用SSI include virtual指令时，需通过自定义配置添加内部代理location：

nginx
location /include-stub {
    internal; # 仅内部访问
    proxy_pass https://uchi.ru/stub;
}

安全配置

Content Security Policy

通过以下环境变量配置CSP头：

dockerfile
# 直接设置CSP内容
ENV CSP_HEADER "script-src 'self';"

# 或从文件加载CSP内容
ENV CSP_HEADER_PATH "/app/csp-header"

# 启用报告模式（仅报告不阻止）
ENV CSP_REPORT_ONLY true