前端自定义挂载静态资源指南

本文档介绍如何通过 SERVICEME NEXT 产品的前端服务挂载自定义页面、定开前端项目或反向代理外部服务。

配置概述

serviceme-frontend 的 Docker 镜像预留了两个可挂载目录，分别用于 自定义 Nginx 配置 与 静态资源托管：

/etc/nginx/custom_conf：自定义 Nginx 配置目录。该目录下的配置文件将被自动合并至 Nginx 的核心 server 配置块中。
/usr/share/nginx/static：静态资源目录，用于托管自定义网页、文件或前端打包结果。

通过在启动容器时挂载上述目录，可灵活扩展前端服务的内容与行为。

挂载自定义 HTML 页面

若需托管单独的 HTML 页面（例如 static/app2/index.html），可按照以下步骤操作：

创建自定义配置文件 custom.conf，内容如下：

location /app2 {
  root /usr/share/nginx/static/;
  index index.html index.htm index.shtml;
  try_files $uri $uri/ /index.html;

  if ($request_filename ~* .*\.html$) {
    add_header Cache-Control "no-cache, no-store";
  }
}

此配置指示 Nginx 在访问 https://<域名>/app2 时加载指定页面。

启动 Docker 容器：

Linux / macOS 环境：

docker run -p 80:80 \
-e SML_BACKEND_URL=https://dev.next.serviceme.com/webapi/ \
-e SML_KNOWLEDGE_BACKEND_URL=https://dev.next.serviceme.com/knowledge-webapi/ \
-v ./custom.conf:/etc/nginx/custom_conf/custom.conf \
-v ./static:/usr/share/nginx/static \
servicemerelease.azurecr.io/serviceme-frontend:4.0.0-rc.2-build.5

Windows 环境：

docker run -p 80:80 `
-e SML_BACKEND_URL=https://dev.next.serviceme.com/webapi/ `
-e SML_KNOWLEDGE_BACKEND_URL=https://dev.next.serviceme.com/knowledge-webapi/ `
-v ${PWD}\custom.conf:/etc/nginx/custom_conf/custom.conf `
-v ${PWD}\static:/usr/share/nginx/static `
servicemerelease.azurecr.io/serviceme-frontend:4.0.0-rc.2-build.5

启动成功后，访问 http://localhost/app2 即可查看托管页面。

挂载定开前端项目

该方案支持挂载自定义开发的前端项目（如 React、Vue、Angular、Vite 等），技术栈不限。
在部署前需正确配置项目的 打包路径（base） 和 路由根目录（basename）。

1. 以 Vite 项目为例

假设需部署到 localhost/app1 路径下，在 vite.config.ts 中添加：

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  base: "/app1/", // 指定打包根路径
});

2. 配置 React Router 路由根目录

createBrowserRouter(routes, {
  basename: import.meta.env.BASE_URL
});

这样可确保应用在指定子路径下正常加载。
打包完成后，将构建结果放置在 static/app1/ 目录，并按前述方式启动容器即可访问。

反向代理外部服务

Nginx 配置可支持标准反向代理。
例如，将 /app3 路径代理至外部网站：

location /app3 {
  proxy_pass https://example.com/;
}

此配置可用于嵌入外部网页、文档或第三方系统。

反向代理定开后端服务

若需要在前端路径下访问内部容器服务（如自定义交付后端），可使用以下配置：

location /custom-backend/ {
  proxy_pass http://serviceme_elc/;
  proxy_connect_timeout 240s;
  proxy_read_timeout 240s;
  proxy_send_timeout 240s;
  proxy_buffering off;
}

注意：

前端容器与后端容器需位于同一 Docker 网络；

Docker 会自动将容器名称（如 serviceme_elc）解析为主机域名。

挂载指定静态文件

某些外部系统（如企业微信）在对接时需要在根域名下放置特定验证文件。
例如，需在根目录下挂载 WW_verify_asD8saBGs.txt 文件，可使用以下配置：

location = /WW_verify_asD8saBGs.txt {
  root /usr/share/nginx/static/;
}

将该文件放入 ./static/ 目录，并挂载配置与静态目录：

docker run \
-v ./custom.conf:/etc/nginx/custom_conf/custom.conf \
-v ./static:/usr/share/nginx/static \
servicemerelease.azurecr.io/serviceme-frontend:4.0.0-rc.2-build.5

覆盖产品静态资源

自定义的 Nginx 配置优先级高于产品默认配置，因此可用于覆盖内置静态资源。
例如自定义产品的 PWA 清单与图标：

location ~* ^/(manifest.webmanifest|customer-logo.svg)$ {
    root /usr/share/nginx/static/;
}

在 ./static 目录中放入自定义文件，如：

manifest.webmanifest

{
  "$schema": "https://json.schemastore.org/web-manifest-combined.json",
  "name": "SERVICEME-自定义",
  "short_name": "SERVICEME",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#ffffff",
  "lang": "en",
  "scope": "./",
  "description": "测试版配置",
  "icons": [
    {
      "src": "/customer-logo.svg",
      "sizes": "any",
      "type": "image/svg+xml"
    }
  ]
}

总结

通过上述方案，管理员可在不修改产品核心代码的情况下实现以下功能：

快速挂载自定义网页或静态资源；
部署独立前端项目；
反向代理外部或内部服务；
覆盖产品默认资源文件。

该机制大幅提升了 SERVICEME NEXT 的可扩展性与灵活集成能力，适用于企业多场景部署及定制化需求。

配置概述​

挂载自定义 HTML 页面​

挂载定开前端项目​

1. 以 Vite 项目为例​

2. 配置 React Router 路由根目录​

反向代理外部服务​

反向代理定开后端服务​

挂载指定静态文件​

覆盖产品静态资源​

总结​