# @equinor/subsurface-app-management 中文文档

规范地址：https://npmcn.com/package/%40equinor/subsurface-app-management/

版本：5\.6\.2
npm 元数据更新时间：2026-11-10T19:11:38.994Z
中文译文更新时间：2026-11-13T20:13:09.623Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40equinor/subsurface-app-management
原文对照：https://npmcn.com/package/%40equinor/subsurface-app-management/?lang=original
项目主页：https://github.com/equinor/subsurface-app-management#readme
源码仓库：https://github.com/equinor/subsurface-app-management

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：100 kB，153 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0，@tanstack/react-query \*，@tanstack/react-router \*
- 首次发布：2024-07-01T12:45:51.318Z
- 最新版本发布：2026-11-10T19:11:38.606Z
- 近 30 天下载量：20228（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：88（近 12 个月 19 个）

## 中文简介

反应 Typescript 组件/ 呼克以等效/ sam 进行通信

## 安装

```sh
npm install @equinor/subsurface-app-management
```

也可以使用：`pnpm add @equinor/subsurface-app-management`、`yarn add @equinor/subsurface-app-management`、`bun add @equinor/subsurface-app-management`

## README

![intro-logo](https://raw.githubusercontent.com/equinor/amplify-components/main/static/amplify_logo.png)

此软件包包含用于通信的组件、 utils、 提供者和钩子 `equinor/SubsurfAppManagement` 由扩充团队开发.

# 快速链接

-   [故事书](https://subsurface-management-storybook.app.radix.equinor.com/)

# 建筑和出版

合并代码后自动构建和发布 `main` 分支,如果包.json版本号更高.

# 最新版本

[![main](https://img.shields.io/npm/v/@equinor/subsurface-app-management?color=%23c3f3d2&label=%40equinor%2Fsubsurface-app-management&logo=npm&)](https://www.npmjs.com/package/@equinor/subsurface-app-management)

# 通过 nginx 代理应用程序透视

自动屏蔽器屏蔽请求 `*.in.applicationinsights.azure.com`这样 `ApplicationInsightsProvider` 发送遥测到 同源路径 `/ai/v2/track` 而Nginx将它转发给Azure. 跟踪是可选的:没有 `APPLICATION_INSIGHTS_CONNECTION_STRING` 应用程序没有追踪到任何东西,Nginx不会暴露代理路径. 摄入量 主机从 `IngestionEndpoint` 在连接字符串中,返回到应用程序 Insights 默认值 (单位:千美元)`dc.services.visualstudio.com`) 当它没有,所以不需要单独的主机变量.

将下面的文件复制到您的应用程序 Repo 中, 替换已有的文件( 例取自 `equinor/sam-frontend`这样 保留您的应用程序特定部分, 如端口、运行时变量和构建步骤等 。 与应用程序有关的行 每个文件上方的注释都标出"洞察".

## 1\. 创建 `proxy/ai-proxy.conf.template`

```nginx
location = /ai/v2/track {
    limit_req zone=ai burst=20 nodelay;
    limit_req_status 429;
    client_max_body_size 1m;

    proxy_pass https://${APPLICATION_INSIGHTS_INGESTION_HOST}/v2/track;
    proxy_ssl_server_name on;
    proxy_ssl_verify on;
    proxy_ssl_verify_depth 3;
    proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
    proxy_set_header Host ${APPLICATION_INSIGHTS_INGESTION_HOST};
    proxy_set_header X-Forwarded-For $remote_addr;
}
```

## 2\. 替换 `proxy/nginx.conf`

用下面的文件替换文件 。 更改对标准设置: `limit_req_zone` 线条和 `include /etc/nginx/ai-proxy.conf;` 线条。 调整 `listen`,则 `/api/` 如果您有不同的话, 代理和其他应用程序特定部件 .

```nginx
limit_req_zone $binary_remote_addr zone=ai:10m rate=5r/s;

server {
    listen       5001;
    server_name  localhost;

    root   /usr/share/nginx/html;

    include /etc/nginx/conf.d/securityheaders.conf;

    # Application Insights proxy (empty file when APPLICATION_INSIGHTS_CONNECTION_STRING isn't set)
    include /etc/nginx/ai-proxy.conf;

    location /api/ {
        client_max_body_size 100M;
        proxy_pass ${API_URL};
    }

    location / {
        index  index.html index.htm;
        try_files $uri /index.html;
    }

    location /env-config.js {
        add_header Cache-Control "no-cache";
        proxy_cache_bypass $http_pragma;
        proxy_cache_revalidate on;
        expires off;
        access_log off;
    }

    location /env.sh {
        deny all;
    }

    location ~ \.html$ {
        add_header Cache-Control "no-cache";
        proxy_cache_bypass $http_pragma;
        proxy_cache_revalidate on;
        expires off;
        access_log off;

        include /etc/nginx/conf.d/securityheaders.conf;
    }
}
```

> `ai-proxy.conf` 一定要住进去 `/etc/nginx/`没有 `/etc/nginx/conf.d/`. nginx 自动包含所有内容 `conf.d/*.conf` 输入 `http` 语境,其中 `location` 无效,但无法启动.

## 3\. 替换 `env.sh`

用下面的文件替换文件 。 更改对标准设置: `if` 块在底部。 自己留着吧 `value=...` 行(每个运行时间变量一个,匹配) `radixconfig.yaml`如果两者不同.

```sh
#!/bin/sh

# Add assignment
echo "window._env_ = {" >>./env-config.js

# For all the environment variables we want to have at
# runtime (one to one with Radixconfig)

value=$(printf '%s\n' "${CLIENT_ID}")
echo "  CLIENT_ID: \"$value\"," >>./env-config.js

value=$(printf '%s\n' "${API_CLIENT_ID}")
echo "  API_CLIENT_ID: \"$value\"," >>./env-config.js

value=$(printf '%s\n' "${NAME}")
echo "  NAME: \"$value\"," >>./env-config.js

value=$(printf '%s\n' "${API_URL}")
echo "  API_URL: \"$value\"," >>./env-config.js

value=$(printf '%s\n' "${API_SCOPE}")
echo "  API_SCOPE: \"$value\"," >>./env-config.js

value=$(printf '%s\n' "${ENVIRONMENT_NAME}")
echo "  ENVIRONMENT_NAME: \"$value\"," >>./env-config.js

value=$(printf '%s\n' "${APPLICATION_INSIGHTS_CONNECTION_STRING}")
echo "  APPLICATION_INSIGHTS_CONNECTION_STRING: \"$value\"," >>./env-config.js

echo "}" >>./env-config.js

# Application Insights proxy (optional): only render the location when a connection string is set.
# The host comes from its IngestionEndpoint, falling back to the Application Insights default.
if [ -n "${APPLICATION_INSIGHTS_CONNECTION_STRING}" ]; then
  APPLICATION_INSIGHTS_INGESTION_HOST=$(printf '%s' "${APPLICATION_INSIGHTS_CONNECTION_STRING}" | tr ';' '\n' | sed -n 's/^IngestionEndpoint=https\{0,1\}:\/\/\([^/]*\).*/\1/p' | head -n 1)
  export APPLICATION_INSIGHTS_INGESTION_HOST="${APPLICATION_INSIGHTS_INGESTION_HOST:-dc.services.visualstudio.com}"
  envsubst '${APPLICATION_INSIGHTS_INGESTION_HOST}' </etc/nginx/ai-proxy.conf.template >/etc/nginx/ai-proxy.conf
else
  : >/etc/nginx/ai-proxy.conf
fi

# Update nginx.conf and securityheaders.conf with relevant environment variables
envsubst '${API_URL}' </etc/nginx/conf.d/default.conf.template >/etc/nginx/conf.d/default.conf
envsubst '${API_URL}' </etc/nginx/conf.d/securityheaders.conf.template >/etc/nginx/conf.d/securityheaders.conf
```

## 4\. 替换 `Dockerfile`

用下面的文件替换文件 。 更改对标准设置: `ai-proxy.conf.template` `COPY` 和两个 `ai-proxy.conf` 线条 `RUN`调整建设阶段和 `EXPOSE` 端口到您的应用程序.

```dockerfile
# Base
FROM imbios/bun-node:22-alpine AS base
WORKDIR /app
COPY package.json ./
COPY bun.lock ./
COPY tsconfig.json ./
COPY vite.config.ts ./
COPY index.html ./
COPY src ./src
COPY public ./public

# Install dependencies and build
RUN bun install --frozen-lockfile && bun run build

# STAGE 2 => SETUP NGINX and Run
FROM nginxinc/nginx-unprivileged:alpine
USER 0
# Clear default nginx html file
RUN rm -rf /usr/share/nginx/html/*
COPY --from=base /app/dist /usr/share/nginx/html
COPY proxy/nginx.conf /etc/nginx/conf.d/default.conf.template
COPY proxy/securityheaders.conf /etc/nginx/conf.d/securityheaders.conf.template
COPY proxy/ai-proxy.conf.template /etc/nginx/ai-proxy.conf.template

EXPOSE 5001

# Copy shell script to container to handle runtime environment variables
WORKDIR /usr/share/nginx/html
COPY ./env.sh .

RUN rm -rf ./env-config.js \
  && touch ./env-config.js \
  && touch /etc/nginx/ai-proxy.conf \
  && chown nginx ./env-config.js /etc/nginx/ai-proxy.conf \
  && chown -R nginx /etc/nginx/conf.d \
  && chown -R nginx /usr/share/nginx/html \
  && chmod +x ./env.sh

USER 101

CMD ["/bin/sh", "-c", "./env.sh && nginx -g \"daemon off;\""]
```

## 5\. 最新情况 `radixconfig.yaml`

对于每个应该跟踪的环境,设置连接字符串. 代理目标从它的 `IngestionEndpoint` 自动( 或应用程序 Insights 默认, 如果没有) 。 对于没有环境 追踪,设定为 `''` 或弃去.

```yaml
APPLICATION_INSIGHTS_CONNECTION_STRING: 'InstrumentationKey=...;IngestionEndpoint=https://northeurope-4.in.applicationinsights.azure.com/;...'
```

## 6\. 核实

```sh
docker build -t app .
docker run --rm -d --name app-test -p 5001:5001 -e APPLICATION_INSIGHTS_CONNECTION_STRING='InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://northeurope-4.in.applicationinsights.azure.com/' app
curl -i -X POST http://localhost:5001/ai/v2/track -d '[]'   # reaches Azure (200/400), not 404/502
docker stop app-test

# No connection string set: nginx still starts without the proxy path
docker run --rm -d --name app-test -p 5001:5001 app
docker logs app-test
docker stop app-test
```

替换 `5001` 端口为您 `nginx.conf` 监听,并添加应用程序的其他需要变量(`NAME`, (中文(简体) ), `ENVIRONMENT_NAME`, (中文(简体) ), `API_URL`如果需要的话.

## 常见问题

### @equinor/subsurface-app-management 是什么？

反应 Typescript 组件/ 呼克以等效/ sam 进行通信

### 如何安装 @equinor/subsurface-app-management？

在项目目录运行 npm install @equinor/subsurface-app-management，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）、@tanstack/react-query（\*）、@tanstack/react-router（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @equinor/subsurface-app-management 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @equinor/subsurface-app-management 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @equinor/subsurface-app-management 可以商用吗？

@equinor/subsurface-app-management 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @equinor/subsurface-app-management 的下载量有多少？

根据 npm 官方下载统计，@equinor/subsurface-app-management 在 2026/10/14 – 2026/11/12 这 30 天内被下载 20,228 次，日均约 674 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @equinor/subsurface-app-management 还在维护吗？

最新版本 5\.6\.2 发布于 2026/11/11（3 天前）；至今共发布 88 个版本，其中过去 12 个月发布了 19 个；首次发布于 2024/07/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。