Entity Search Web App

![构建状态]([] ![许可证]([]

!截图

概述

这是一个实体搜索应用的实现，它使用Senzing REST API服务器微服务通过Web界面访问Senzing API的功能。

相关制品

1. DockerHub
2. Helm Chart

目录

1. Entity Search Web App
   1. 概述
      1. 相关制品
      2. 目录
      3. 图例
   2. 准备工作
      1. 必备软件
      2. 拉取最新Docker镜像
      3. 克隆仓库
      4. 配置
   3. 使用docker-compose
   4. 使用docker
      1. Docker网络
      2. 运行
      3. 使用SSL
         1. 前提条件
         2. 自签名证书
         3. 使用Docker Stack配置SSL
      4. 管理区域
         1. 管理区域配置
      5. 安全防护措施
         1. CORS（跨域请求）
         2. CSP（内容安全策略）
      6. 隔离环境
      7. 从源代码构建
   5. 开发
      1. 开发服务器
      2. 生产服务器
      3. 代码脚手架
   6. 测试
      1. 运行单元测试
      2. 运行端到端测试
   7. 更多帮助

图例

1. :thinking: - "思考者"图标表示可能需要一些额外的思考。也许你需要做出一些选择，或者这是一个可选步骤。
2. :pencil2: - "铅笔"图标表示执行前可能需要修改说明。
3. :warning: - "警告"图标表示有需要注意的复杂情况，请留意。

准备工作

必备软件

需要安装以下软件：

1. docker
2. docker-compose

拉取最新Docker镜像

1. 从Docker Hub拉取此应用的最新版本。示例：

   console
   sudo docker pull senzing/entity-search-web-app
   

2. 从DockerHub拉取最新的API服务器镜像。示例：

   console
   sudo docker pull senzing/senzing-api-server
   

克隆仓库

1. 设置这些环境变量值：

   console
   export GIT_ACCOUNT=senzing
   export GIT_REPOSITORY=entity-search-web-app
   export GIT_ACCOUNT_DIR=~/${GIT_ACCOUNT}.git
   export GIT_REPOSITORY_DIR="${GIT_ACCOUNT_DIR}/${GIT_REPOSITORY}"
   

2. 按照clone-repository中的步骤安装Git仓库。

配置

通过环境变量或命令行参数指定的配置值：

• SENZING_DATA_VERSION_DIR
• SENZING_ETC_DIR
• SENZING_G2_DIR
• SENZING_NETWORK
• SENZING_RUNAS_USER
• SENZING_VAR_DIR

使用docker-compose

1. 在docker-compose环境中运行。示例：

   console
   cd ${GIT_REPOSITORY_DIR}
   sudo \
     docker-compose up senzing-webapp
   

2. 验证容器是否正在运行且可访问：

   1. 在Web浏览器中打开http://localhost:8081（或用主机名或IP替换localhost）。

   2. 或者，使用curl。示例：

      console
      curl [***]
      

使用docker

Docker网络

以下Docker容器通过Docker网络通信。

1. :thinking: 查找或创建Docker网络。执行以下任一过程。

   1. 查找Docker网络。

      1. 列出Docker网络。示例：

         console
         sudo docker network ls
         

      2. :pencil2: 指定Docker网络。从docker network ls的NAME列中选择值。示例：

         console
         export SENZING_NETWORK=*网络名称*
         

   2. 创建Docker网络。

      1. :pencil2: 指定网络名称。示例：

         console
         export SENZING_NETWORK=sz-api-network
         

      2. 创建Docker网络。示例：

         console
         sudo docker network create -d bridge ${SENZING_NETWORK}
         

2. 构造docker run的参数。示例：

   console
   export SENZING_NETWORK_PARAMETER="--net ${SENZING_NETWORK}"
   

运行

1. 启动senzing-api-server。示例：

   console
   sudo docker run \
     --interactive \
     --name=senzing-api-server \
     --publish 8080:8080 \
     --rm \
     --tty \
     --volume ${SENZING_DATA_VERSION_DIR}:/opt/senzing/data \
     --volume ${SENZING_ETC_DIR}:/etc/opt/senzing \
     --volume ${SENZING_G2_DIR}:/opt/senzing/g2 \
     --volume ${SENZING_VAR_DIR}:/var/opt/senzing \
     ${SENZING_NETWORK_PARAMETER} \
     senzing/senzing-api-server \
       -concurrency 10 \
       -httpPort 8080 \
       -bindAddr all \
       -iniFile /etc/opt/senzing/G2Module.ini
   

2. 运行实体搜索Web应用。示例：

   console
   sudo docker run \
     --env SENZING_API_SERVER_URL=[***] \
     --env SENZING_WEB_SERVER_PORT=8081 \
     --interactive \
     --name=senzing-webapp \
     --publish 8081:8081 \
     --rm \
     --tty \
     ${SENZING_NETWORK_PARAMETER} \
     senzing/entity-search-web-app
   

3. 验证容器是否正在运行且可访问：

   1. 在Web浏览器中打开http://localhost:8081（或用主机名或IP替换localhost）。

   2. 或者，使用curl。示例：

      console
      curl [***]
      

使用SSL

senzing-webapp的主要Docker镜像支持通过HTTPS运行其Web服务器。为了以安全方式部署Web应用，必须在swarm配置中使用该镜像，而不是独立服务。有关swarm以及为什么这是必需的更多信息，请参见Docker Swarm Secrets

前提条件

1. API版本> 1.25的docker客户端和守护程序。可以通过输入docker version检查docker客户端运行的API版本。
2. Web服务器的有效SSL证书（server.key和server.cert）。（如果没有，可以临时使用自签名证书）

自签名证书

自签名证书足以建立安全的HTTPS连接，用于开发目的。不应在生产环境中使用，但如果只是想测试加密功能，这是一个可行的短期解决方案。需要在系统上安装OpenSSL来生成这些证书。可以进行谷歌搜索或查看这篇文章，生成server.cert和server.key文件后再回到本节。

使用Docker Stack配置SSL

为方便起见，我们包含了一个专门用于SSL配置的docker compose 文件。如果不熟悉stack的工作方式，建议从此示例开始（出于多种原因，stack部署需要不同的yml文件）。

打开该示例，会在文件底部看到两行：

yaml
  SZ_WEBAPP_SSL_CERT:
    file: '../CERTS/server.cert'
  SZ_WEBAPP_SSL_KEY:
    file: '../CERTS/server.key'

这些行告诉docker将两个密钥传递给docker compose文件中定义的服务。这两行应指向要使用的server.key和server.cert文件的位置。

senzing-api-server服务的配置可能与你的运行配置不同。应将已正常工作的docker-compose.yml文件中定义的配置选项复制到docker-stack.yml文件中。

senzing-webapp服务定义下的其他重要行是：

yaml
secrets:
      - source: SZ_WEBAPP_SSL_CERT
        target: server.cert
        uid: '1001'
        gid: '1001'
      - source: SZ_WEBAPP_SSL_KEY
        target: server.key
        uid: '1001'
        gid: '1001'

它们告诉webapp服务使用文件底部定义的密钥内容。这类似于传入文件，但docker密钥的工作方式比较特殊。

接下来，通过输入sudo SENZING_DATA_VERSION_DIR=${SENZING_DATA_VERSION_DIR} SENZING_ETC_DIR=${SENZING_ETC_DIR} SENZING_G2_DIR=${SENZING_G2_DIR} SENZING_VAR_DIR=${SENZING_VAR_DIR} docker stack deploy -c docker-stack.yml senzing-webapp将yml文件中定义的服务部署到swarm管理器。

通过输入docker stack ps senzing-webapp检查服务是否成功启动。结果应如下所示：

bash
ID                  NAME                                  IMAGE                               NODE                DESIRED STATE       CURRENT STATE               ERROR               PORTS
7mxc4jru51pl        senzing-webapp_senzing-api-server.1   senzing/senzing-api-server:latest   americium           Running             Running about an hour ago
rnguy9d2incb        senzing-webapp_senzing-webapp.1       senzing/entity-search-web-app:ssl   americium           Running             Running about an hour ago

然后可以使用curl -kvv https://localhost:8081向web服务器发起curl请求。输出应类似于以下内容：

bash
* Rebuilt URL to: https://localhost:8081/
*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to localhost (127.0.0.1) port 8081 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* successfully set certificate verify locations:
*   CAfile: /etc/ssl/certs/ca-certificates.crt
  CApath: /etc/ssl/certs
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.3 (IN), TLS Unknown, Certificate Status (22):
* TLSv1.3 (IN), TLS handshake, Unknown (8):
* TLSv1.3 (IN), TLS Unknown, Certificate Status (22):
* TLSv1.3 (IN), TLS handshake, Certificate (11):
* TLSv1.3 (IN), TLS Unknown, Certificate Status (22):
* TLSv1.3 (IN), TLS handshake, CERT verify (15):
* TLSv1.3 (IN), TLS Unknown, Certificate Status (22):
* TLSv1.3 (IN), TLS handshake, Finished (20):
* TLSv1.3 (OUT), TLS change cipher, Client hello (1):
* TLSv1.3 (OUT), TLS Unknown, Certificate Status (22):
* TLSv1.3 (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
* ALPN, server accepted to use http/1.1
* Server certificate:
*  subject: C=US; ST=OR; L=SenzingTown; O=Senzing; CN=localhost
*  start date: Nov 13 00:49:12 2019 GMT
*  expire date: Nov 12 00:49:12 2020 GMT
*  issuer: C=US; ST=OR; L=SenzingTown; O=Senzing; CN=localhost
*  SSL certificate verify result: self signed certificate (18), continuing anyway.
* TLSv1.3 (OUT), TLS Unknown, Unknown (23):
> GET / HTTP/1.1
> Host: localhost:8081
> User-Agent: curl/7.58.0
> Accept: */*

在此示例中使用的是自签名证书，但重要的是看到TLSvx.x握手和*Server certificate:*响应块。此时，可以在普通浏览器（Chrome、Firefox、Edge等）中打开服务器实例，例如https://localhost:8081。地址栏中地址旁边应显示证书提供的SSL信息。如果是自签名证书，会看到警告消息，询问是否继续，这是正常的。

可以使用docker stack rm senzing-webapp关闭swarm节点。

管理区域

有一个管理区域，可用于创建新数据源并将数据导入这些数据源。要访问此功能，API服务器版本必须>=1.7.11，并且必须使用-enableAdmin标志启动，设置为true。

然后可以通过在运行webapp的同一域/主机名上浏览到/admin来访问管理区域。系统会提示输入Api Token，这是用于防止未经授权操作数据的默认安全机制。令牌在服务器启动时随机生成，并输出到启动容器所用的终端的标准输出中。出现提示时，将此令牌复制并粘贴到登录框中。

管理区域配置

支持三种安全模式：

1. JWT/令牌基于：随机生成的密钥/短语/种子。这是默认模式，因为它是自包含的，不需要管理员或用户进行任何其他配置。
2. SSO/代理：此模式向/admin/auth/sso/status发起请求，并检查响应是否为200。如果响应不是200，则用户被重定向到SENZING_WEB_SERVER_ADMIN_AUTH_REDIRECT环境变量值定义的登录页面。SSO/代理应配置为当用户未登录时，对/admin/auth/sso/status的请求返回401/403。
3. 无：不推荐此模式。仅用于开发或调试目的。

变量：

1. SENZING_WEB_SERVER_ADMIN_AUTH_MODE定义管理区域使用的安全模式。可能的值为SSO、JWT、EXTERNAL、NONE。
2. SENZING_WEB_SERVER_ADMIN_AUTH_REDIRECT定义用户未通过身份验证时重定向的路径。在SSO