codecentric/single-page-application-server

单页应用服务器

!https://github.com/codecentric/single-page-application-server/workflows/Update%20Docker%20Images/badge.svg

该容器镜像提供了使用Nginx作为Web服务器来部署单页应用（SPA）的基础。

使用此镜像部署应用时，对应的Helm chart也可在https://hub.docker.com/r/codecentric/single-page-application-server-chart%E8%8E%B7%E5%8F%96%E3%80%82

标签

以下标签每周自动更新，包含最新的Nginx基础镜像：

• latest（别名：1-nginx-stable-alpine）
• 1（别名：1-nginx-stable-alpine）
• latest-nginx-stable-alpine（别名：1-nginx-stable-alpine）
• 1-nginx-stable-alpine
• latest-nginx-mainline-alpine（别名：1-nginx-mainline-alpine）
• 1-nginx-mainline-alpine

同时提供特定Nginx版本的额外标签。

示例

Angular和React的使用示例位于examples目录中。

通用特性

• SPA路由处理：不匹配静态文件的路由将返回index.html，但.js、.css等资源除外。
• 动态配置：容器启动时配置SPA，配置可通过window.spaConfig访问。
• 环境特定配置：基于端口和域名自定义设置。
• 资源缓存：带哈希的资源（哈希至少8个字符）将被永久缓存。
• HTTP/2：默认对HTTPS连接启用。
• Helm Chart：提供通用https://github.com/codecentric/single-page-application-server/blob/master/chart/README.md%E7%94%A8%E4%BA%8E%E4%BD%BF%E7%94%A8%E6%AD%A4%E9%95%9C%E5%83%8F%E7%9A%84%E5%BA%94%E7%94%A8%E3%80%82

安全特性

• 内容安全策略（CSP）：默认严格，自动白名单服务器API端点。
• 引用策略：默认禁用以防止信息泄露。
• 内容类型嗅探：默认禁用。
• HTTPS：启用HSTS时强制使用；采用https://github.com/OWASP/CheatSheetSeries/blob/1e07c6c894f98af58d8a417eb8df1b20e1b3337e/cheatsheets/TLS_Cipher_String_Cheat_Sheet.md%E3%80%82
• 非root用户：容器以非root用户运行，但可绑定80和443端口。
• 源代码映射：默认禁用。
• 只读根文件系统：容器运行时支持
• 供应链验证：所有镜像使用cosign签名，详见供应链验证。

配置

应用目录

将SPA资源放置在/app/目录下，该目录中的所有文件将由Nginx提供服务。

YAML配置

通过容器启动时的YAML文件配置应用：

1. 默认配置：添加默认配置文件至/config/default.yaml，通常在docker build时添加。
2. 运行时配置：将运行时配置文件挂载至/config/config.yaml，此文件将覆盖默认设置。

示例配置

yaml
default:
  spa_config:
    appTitle: "我的应用"
    endpoints:
      api: "https://api.example.com"

也可定义特定主机的配置：

yaml
default:
  spa_config:
    appTitle: "默认标题"
    endpoints:
      api: "https://api.example.com"
special_host:
  server_names:
    - "special.example.com"
  spa_config:
    appTitle: "特定域名标题"

配置参考

以下配置展示了基础镜像所有可用设置的默认值：

yaml
default:
  # 指定此配置适用的主机名
  server_names:
    # "_"匹配任何主机名
    - "_"
  # index.html中base元素的href属性
  base_href: "/"
  # 此映射中的所有选项将通过`window.spaConfig`在SPA中可用
  # 要启用此功能，还需在index.html中包含spa_config.js
  # 现有spa_config.js将在容器启动时被覆盖
  spa_config:
    # SPA通信的端点映射
    # 若启用.hardening.whitelist_connect_sources，这些端点将自动添加到CSP的connect-src白名单
    endpoints: {}
  access_log:
    # 启用访问日志
    enabled: false
  source_maps:
    # 启用源代码映射
    enabled: false
    # 用于识别源代码映射资源的正则表达式
    regex: "\\.(js|css)\\.map$"
  http:
    enabled: true
    port: 80
    # 若启用HTTPS，是否重定向至HTTPS
    https_redirect: true
    # 应用位于NAT后时，使用不同的HTTPS重定向端口
    # 0 = 使用https.port
    https_redirect_port: 0
    # 纯文本连接默认禁用HTTP/2，因为Nginx仅通过预先了解支持纯文本HTTP/2
    # https://trac.nginx.org/nginx/ticket/816
    http2_enabled: false
  https:
    enabled: false
    port: 443
    # 永久强制使用HTTPS
    hsts_enabled: true
    ssl_certificate: /etc/ssl/default.crt
    ssl_certificate_key: /etc/ssl/default.key
    # 使用推荐值配置支持的TLS协议和密码套件
    # https://github.com/OWASP/CheatSheetSeries/blob/1e07c6c894f98af58d8a417eb8df1b20e1b3337e/cheatsheets/TLS_Cipher_String_Cheat_Sheet.md
    owasp_cipher_string: A
    http2_enabled: true
  keepalive:
    server:
      # 服务器端保持活动客户端连接的超时时间（秒）
      timeout_seconds: 75
  hardening:
    # 禁用引用以防止信息泄露
    referrer_policy: "no-referrer"
    # 防止浏览器猜测内容类型
    x_content_type_options: "nosniff"
    # 启用时，自动将.spa_config.endpoints中的端点添加到CSP的connect-src白名单
    whitelist_spa_config_endpoints_as_connect_sources: true
    # CSP指令映射，将添加到所有HTML和JavaScript文档的HTTP响应中
    content_security_policy:
      base-uri: "'self'"
      block-all-mixed-content: true
      default-src: "'self'"
      form-action: "'self'"
      frame-ancestors: "'self'"
      frame-src: "'self'"
      object-src: "'none'"
      script-src: "'self'"
      style-src: "'self'"

只读根文件系统支持

为增强安全性，可使用只读根文件系统。确保以下目录可写：

• /config/.out：用于文件生成。
• /tmp：Nginx用于缓存文件和nginx.pid。

在Kubernetes中，建议将这些目录挂载为emptyDir类型的可写卷。

供应链验证

当Dockerfile使用codecentric/single-page-application-server作为基础镜像时，使用cosign验证基础镜像：

bash
cosign dockerfile verify Dockerfile \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https\:\/\/github\.com\/codecentric\/single\-page\-application\-server' \
  --base-image-only

可通过克隆此仓库并在examples/angular目录中执行该命令进行测试。

开发

• 配置生成：使用gomplate模板。
• 镜像测试：使用Java和Testcontainers编写。
• Helm Chart测试：使用https://github.com/helm-unittest/helm-unittest Helm插件。

许可证

MIT