#新手

0 关注者 · 74 帖子

初学者标签汇集了面向 InterSystems 数据平台初学者的文章和问题

文章 Nicky Zhu · 十月 31, 2025 20m read

目录

  1. 本文目的
  2. 什么是容器,它们为什么对 IRIS 有意义
     2.1 容器和镜像简介
     2.2 为什么容器对开发者很有用
     2.3 为什么 IRIS 可以很好地与 Docker 配合使用
  3. 先决条件
  4. 安装 InterSystems IRIS 镜像
     4.1 使用 Docker Hub
     4.2 拉取镜像
  5. 运行 InterSystems IRIS 镜像
     5.1 启动 IRIS 容器
     5.2 检查容器状态
     5.3 在容器终端执行代码
     5.4 访问 IRIS 管理门户
     5.5 将容器连接到 VS Code
     5.6 停止或移除容器
     5.7 使用绑定挂载设置特定密码
     5.8 使用持久化 %SYS 卷
      5.8.1 可以使用持久化 %SYS 存储什么
      5.8.2 如何启用持久化 %SYS
  6. 使用 Docker Compose
     6.1 Docker Compose 示例
     6.2 运行 Docker Compose
  7. 使用 Dockerfile 运行自定义源代码
     7.1 Dockerfile 示例
     7.2 Docker Compose 示例
     7.3 了解层、镜像标记和构建与 运行时
     7.4 源代码和初始化脚本
     7.5 使用 Dockerfile 构建镜像
     7.6 在容器化 IRIS 终端中运行指令
  8. 结语和未来计划


1. 本文目的

InterSystems 开发者社区已经有很多优秀的文章解释了 Docker 是什么、最重要的命令以及 InterSystems IRIS 在容器化环境中的多个用例。

本系列文章的目的略有不同。 由于我非常喜欢分步指南,我想创建一份全面的讲解,介绍如何在 InterSystems IRIS 中配置和使用 Docker,我们先从最基础的场景开始,逐步过渡到更高级的场景,例如多命名空间实例、互连容器、与外部系统的集成以及用于了解 UI 的应用程序。

2. 什么是容器,它们为什么对 IRIS 有意义

2.1 容器和镜像简介

按照传统方法,要想运行应用程序,需要将版本与您的操作系统进行匹配,并针对特定目标对其进行打包。 同时,每个应用程序都应当打包,以便专门与某个目标系统配合使用。 如果您希望应用程序在 macOS 和 Windows 上运行,必须更改应用程序设计并针对不同的系统进行打包。Docker 镜像和容器是应用程序部署技术,通过让开发者将软件打包一次并在任何地方运行来解决此问题。

Docker 是一个将软件打包到容器中的软件平台。 Docker 镜像(或容器镜像)是独立的可执行文件,包含创建和运行容器的所有指令(库、依赖项和文件)。 Docker 镜像可共享、可移植,因此您可以一次在多个位置部署同一个镜像。Docker 容器是一个运行时环境,具有运行应用程序代码所需的所有必要组件,无需使用主机依赖项。  

与虚拟机不同,容器是轻量级的。 它们不需要完整的操作系统,只使用特定应用程序所需的二进制文件和库,通过 Docker 引擎直接在主机操作系统上运行,这使其更加高效。 多个隔离的容器可以在同一台计算机上并行启动,互不干扰。

2.2 为什么容器对开发者很有用

  • 隔离:在清晰、可重现的环境中运行,不会影响您的主机系统。
  • 可重现性:确保您的设置在不同的计算机上以相同的方式工作。
  • 轻松设置:使用一个命令,只需几秒钟即可启动 IRIS 实例,无需手动安装。

2.3 为什么 IRIS 可以很好地与 Docker 配合使用

在 Docker 中运行 InterSystems IRIS 有几项优势:

  • 应用程序运行并且可以在隔离的容器中进行测试
  • 可以使用共享版本控制系统(如 Git),无需直接在服务器上操作
  • 容器化环境可以在任何阶段重现,从而在整个软件生命周期中保持一致性。
  • 您的应用程序可以轻松地在每台计算机上运行。

3. 先决条件

要在 Docker 容器中运行 InterSystems IRIS,您必须具有:

4. 安装 InterSystems IRIS 镜像

4.1 使用 Docker Hub

Docker Hub 是 Docker 镜像的中心注册表。 它提供了一个庞大的预构建镜像库,您可以将其作为切入点。 InterSystems 在其中发布官方 IRIS 社区版镜像,您可以下载该镜像以在自己的容器中本地运行 IRIS。 您还可以使用 Docker Hub 推送自己的自定义镜像,以便在团队中共享或分发给社区。Docker Hub 既可以在线使用,也可以嵌入到 Docker Desktop 中。

4.2 拉取镜像

一些常见的 Docker 镜像命令包括:

命令描述
docker pull <image>从 Docker Hub 下载镜像
docker images列出所有本地镜像
docker rmi <image>移除一个或多个镜像

您可以直接在镜像的 Docker Hub 页面上找到确切的拉取命令:

对于 InterSystems IRIS 镜像,该命令为:

docker pull intersystems/iris-community:latest-cd

或者,您可以在 Docker Desktop 搜索栏中搜索 iris-community 并点击 Pull

安装后,您应当拥有在本地镜像中列出的 InterSystems IRIS 镜像:

5. 运行 InterSystems IRIS 镜像

从 Docker Hub 中拉取出 InterSystems IRIS 镜像后,您可以在容器内运行该镜像。

以下是常用的 Docker 容器命令

命令描述
docker run -d <image>以分离模式运行:在后台启动容器并立即将控制权返还给终端。
docker run -p <host>:<container> <img>将主机端口映射到容器端口
docker ps列出正在运行的容器
docker ps -a列出所有容器(包括已停止的容器)
docker exec -it <container> bash在正在运行的容器中执行命令
docker logs <container>查看容器日志
docker stop <container>停止正在运行的容器
docker start <container>启动已停止的容器
docker restart <container>重启容器
docker rm <container>移除容器

5.1 启动 IRIS 容器

您可以通过 Docker Desktop UI 启动名为“my-iris”的 InterSystems IRIS 社区版容器,只需在 Images 面板中点击要运行的镜像的 Run 按钮即可。 对于 InterSystems 镜像,可以指定一些可选的设置,例如在主机上公开哪些端口来与容器内运行的服务进行通信。

可以通过上面显示的菜单完成操作,具体如下:

  • 左侧 → 主机上的端口
  • 右侧 → 容器内的端口

常用 IRIS 端口(容器内)

  • 1972 → 超级服务器端口:由 IRIS 用于网络协议(ObjectScript、JDBC 等)。
  • 52773 → Web 服务器端口:由 IRIS 用于管理门户(Web 界面)。

如果没有显式映射端口,Docker 将在主机上指定随机端口。

或者,可以使用终端来运行容器:

docker run --name my-iris -d --publish 9091:1972 --publish 9092:52773 intersystems/iris-community:latest-cd

在本例中:

  • 主机上的 9091 映射到容器内的 1972(超级服务器)。
  • 主机上的 9092 映射到容器内的 52773(管理门户)。

5.2 检查容器状态

运行此命令后,运行 docker ps 以验证容器是否正常运行。

> docker ps
CONTAINER ID   IMAGE                                   COMMAND                 CREATED         STATUS                            PORTS                                                                                        NAMES
907d4c2b4ab5   intersystems/iris-community:latest-cd   "/tini -- /iris-main"   3 seconds ago   Up 2 seconds (health: starting)   0.0.0.0:9091->1972/tcp, [::]:9091->1972/tcp, 0.0.0.0:9092->52773/tcp, [::]:9092->52773/tcp   my-iris

正在运行的容器也会列在 Docker Desktop Containers 面板中:

相关镜像的状态将是 In Use,如 Images 面板中所示:

5.3 在容器终端执行代码

当容器状态显示 Running 时,表示一切正常。 

您可以进行测试,只需打开容器终端(点击 Docker Desktop 的 Containers 面板内的容器名称并转到 Exec)并输入以下内容即可:

iris session IRIS

这将在 Docker 容器中打开一个 IRIS 终端,您可以在其中使用标准的 ObjectScript 语法来执行命令和脚本。

5.4 访问容器化实例的 IRIS 管理门户

接下来,打开浏览器并导航到:

http://localhost:9092/csp/sys/UtilHome.csp

默认情况下,IRIS 容器使用用户 _SYSTEM 和密码 SYS。登录后需要更改密码。

这将为您提供 IRIS 管理门户的完整访问权限,这样您可以直接从 Web 界面管理命名空间、数据库和其他 IRIS 功能。

5.5 将容器连接到 VSCode IDE

您可以使用映射的超级服务器端口(默认为容器内的 1972,例如主机上的 9091)和 Web 服务器端口(默认为容器内的 52773,例如主机上的 9092)将您喜欢的 IDE(例如 VS Code 或 Studio)连接到 IRIS 容器。 这样您可以直接针对正在运行的容器开发和测试 ObjectScript 代码。

将容器连接到 VSCode:

  • 安装 InterSystems ObjectScript 扩展程序包
  • 打开 InterSystems Server 扩展程序
  • 点击三个点和“Edit server”
  •  
  • 点击“Edit in settings.json”
  • 将此元素添加到“intersystems.servers”json:
"docker_iris": {
    "webServer": {
        "scheme": "http",
        "host": "localhost",
        "port": 9092
    },
    "description": "Connection to Docker container."
}
  • 服务器现已连接。 您可以使用 _SYSTEM 用户登录。
  • 您可以看到,USER 是唯一可用的命名空间:

5.6 停止或移除容器

要停止正在运行的容器,请使用以下命令:

docker stop my-iris

再次启动容器

要再次启动容器,请使用以下命令:

docker start my-iris

移除(删除)容器

要移除容器实例,但移除镜像,请使用:

docker rm my-iris

除非您挂载了卷,否则容器内的所有数据都将丢失(我们将在后续段落中讨论这个问题)。

5.7 使用绑定挂载设置特定密码

在启动容器时,可以使用密码文件设置自定义密码。 该文件将保存在我们的主机上,并使用绑定挂载机制复制到容器中。

当您使用绑定挂载时,主机上的文件或目录将从主机挂载到容器中,从而允许在 Docker 主机上的开发环境和容器之间共享源代码或构建工件。

  • 创建名为 password.txt 的文件,其中仅包含字符串形式的密码(注意! 记下密码,以后会用到)。
  • 复制其路径,本例中为 C:\InterSystems\DockerTest\password\password.txt
  • 运行以下命令:
docker run --name my-iris -d --publish 9091:1972 --publish 9092:52773 --volume "C:\InterSystems\DockerTest:/durable" intersystems/iris-community:latest-cd --password-file /durable/password/password.txt 

容器运行后,可以使用用户 _SYSTEM  和您在密码文件中写下的密码登录。

在 Docker 容器内,您会看到一个 password.txt.done 文件。您的主机文件夹中会有一个相同的文件。

文件扩展名会更改为 .done,以避免密码以纯文本形式保留。 这是 InterSystems IRIS 中对密码文件的标准操作。 因此,在从 password.txt 文件读取密码并将默认 IRIS 用户 (_SYSTEM) 更新为该密码后,出于安全原因,该文件会附加 .done 并移除密码。

您可以使用自定义密码登录管理门户(我告诉过您记下来 :D)。 登录后,InterSystems IRIS 不会强迫您更改密码。

请注意,如果在没有挂载任何持久化卷的情况下移除了容器,然后重启(有关详情,请参阅下一段),则不会再次从 password.txt 文件中读取密码,因为它已被替换为 password.txt.done。 如果是这种情况,将使用标准的“SYS”密码。 

5.8 使用特定的持久化卷启动容器

默认情况下,当您使用 docker rm <container's name> 命令移除正在运行的 Docker 容器时,保存在该容器内的任何内容都将消失。

为了避免丢失数据,InterSystems IRIS 提供了持久化 %SYS 功能。 这可以让实例将所有重要的文件都存储在您的主机上,以便在容器和实例重启后它们仍然存在。

5.8.1 可以使用持久化 %SYS 存储什么?

一些示例包括:

  • 配置文件(iris.cpfhttpd.conf
  • Web 网关配置和日志 (/csp)
  • 系统数据库(IRISUSERIRISSECURITYIRISTEMP 等)
  • 日志、写入镜像文件 (WIJ) 和临时文件
  • 日志文件(messages.logSystemMonitor.log 等)
  • 许可证密钥 (iris.key)
  • 您创建的任何其他数据库

5.8.2 如何启用持久化 %SYS

首先,从主机中选择一个文件夹,如 C:\InterSystems\DockerTest

  • 在 Linux 上,创建 irisowner 用户并为其授予目录所有权,确保 IRIS 可以写入该文件夹:
adduser irisowner
chown -R irisowner:irisowner /InterSystems/DockerTest
  • 在 Windows 上,您可以跳过这一段,因为 Docker Desktop 将使用您当前的 Windows 用户权限挂载该文件夹。

然后,挂载您的主机文件夹并使用 ISC_DATA_DIRECTORY 变量告知 IRIS 将其持久化数据写入何处:

  --volume "C:\InterSystems\DockerTest:/durable" --env ISC_DATA_DIRECTORY=/durable/iris

在终端上运行的完整指令是:

docker run --name my-iris -d --publish 9091:1972 --publish 9092:52773 --volume "C:\InterSystems\DockerTest:/durable" --env ISC_DATA_DIRECTORY=/durable/iris intersystems/iris-community:latest-cd --password-file /durable/password/password.txt

此时,您可以检查您的容器,看到一个持久化文件夹已装载并包含目录 iris/(对于持久化 %SYS)和 password/。 在主机上,您也可以看到以下两个目录:

如果容器停止并被移除,当您使用相同的 Docker Compose 命令重新创建容器时,IRIS 将使用 iris/ 文件夹中的数据恢复其先前的状态(用户、配置、日志、数据库等),因此不会丢失任何内容。 您可以通过创建 Web 应用程序、停止并移除容器,然后再次创建来进行测试。 如果不使用持久化 %SYS 功能,每次移除容器并启动新实例时,%SYS 内的任何更改都会丢失。

请注意,如果删除了 iris/ 文件夹,下次启动 IRIS 容器时,由于无法找到先前的 %SYS 数据,它将像在全新安装中一样进行初始化。 将创建一个全新的 iris/ 文件夹。

6. 使用 Docker Compose 

到目前为止,您一直在使用一个长命令 docker run 启动 InterSystems IRIS。 这虽然可行,但很快就会难以使用普通的 Shell 命令来管理一切。

Docker Compose 是一个 YAML 配置文件,用于定义如何运行一个或多个容器。这简化了整个应用程序栈的控制,使管理服务、网络和卷变得更加容易。 只需一个命令,即可从配置文件创建并启动所有服务。

以下是 Docker compose 的常用命令

命令描述
docker compose up -d以分离模式启动 docker-compose.yml 中定义的所有服务(默认情况下,使用当前文件夹中的 docker-compose.yml 文件)。
docker compose -f ./path/to/docker-compose.yml up -d从另一个目录中的 compose 文件启动服务。
docker compose down停止并移除由 docker compose up 创建的所有容器、网络和卷。
docker compose ps列出由 Compose 管理的容器。
docker compose logs查看 Compose 文件中定义的所有服务的日志。
docker compose logs <service>查看特定服务(例如,iris)的日志。
docker compose exec <service> bash在由 Compose 管理的正在运行的容器内打开一个 Shell。
docker compose stop停止正在运行的容器,但不将其移除。
docker compose start启动之前停止的容器。
docker compose restart重启 Compose 文件中定义的所有容器。
docker compose build构建或重建由 Dockerfile 定义的服务。
docker compose pull拉取服务的最新镜像。
docker compose config验证并查看 Compose 文件中的合并配置。

6.1 Docker Compose 示例

要使用 Docker Compose,必须创建一个 docker-compose.yml 文件,其中包含您要创建和启动的容器的所有配置。

这样一来,以下命令:

docker run --name my-iris -d --publish 9091:1972 --publish 9092:52773 --volume "C:\InterSystems\DockerTest:/durable" --env ISC_DATA_DIRECTORY=/durable/iris intersystems/iris-community:latest-cd --password-file /durable/password/password.txt

可被替换为下方的 docker-compose.yml

# docker-compose.yml     
services:
  iris:
    container_name: my-iris
    image: intersystems/iris-community:latest-cd
    init: true
    volumes:
      # System/persistent data (IRIS installation, databases, etc.)# On Windows, you can use either: "C:\\InterSystems\\DockerTest:/durable"
      - C:/InterSystems/DockerTest:/durable
    ports:
      - "9092:52773"# Management Portal / REST APIs
      - "9091:1972"# SuperServer port
    environment:
      - ISC_DATA_DIRECTORY=/durable/iris
    # Use the password file to log within the container
    command: --password-file /durable/password/password.txt

6.2 运行 Docker Compose 

在保存 Docker Compose 文件的目录中打开一个终端(或使用 -f 选项)并运行以下命令:

docker compose up -d

您的 IRIS 容器将以 Docker Compose 文件中指定的确切配置启动。

在 Docker Desktop 中,您现在可以看到一个名为“dockertest”的 Compose 栈(它采用保存 Docker Compose 的文件夹的名称)已经创建并与容器“my-iris”相关联:

7. 使用 Dockerfile 运行自定义源代码

到目前为止,您一直在直接从官方 Docker 镜像运行 InterSystems IRIS。 不过,在构建镜像时,我们可能需要自动加载镜像中的 ObjectScript 类或其他自定义代码。

Dockerfile是一个文本文件,其中包含从基础镜像(如 intersystems/iris-community:latest-cd)开始构建镜像的指令。 使用 Dockerfile,我们可以将自定义源代码添加到容器中,并在构建镜像时运行自定义命令。

7.1 Dockerfile 示例

下一个示例提供了一个执行以下操作的 Dockerfile:

  • 从官方 InterSystems IRIS 镜像启动镜像。
  • 将应用程序代码从 src/ 文件夹复制到容器。
  • 运行脚本来导入类并初始化容器化的应用程序,然后将日志保存到日志文件中。
  • 公开默认的 InterSystems IRIS 端口。

7.2 Docker Compose 示例

您还应当修改 Docker Compose,以指定从当前文件夹中的 Dockerfile 构建镜像:

# docker-compose.yml     
services:
  iris:
    container_name: my-iris
    build: # this tells Docker to build a new image based on the one specified in the Dockerfile
      context: .        # build the image from local Dockerfile
      dockerfile: Dockerfile
    image: my-modified-iris-image:latest   # give the new image a new tag to avoid overriding the base image
    init: true
    volumes:
      # System/persistent data (IRIS installation, databases, etc.)# On Windows, you can use either: "C:\\InterSystems\\DockerTest:/durable"
      - C:/InterSystems/DockerTest:/durable
    ports:
      - "9092:52773"# Management Portal / REST APIs
      - "9091:1972"# SuperServer port
    environment:
      - ISC_DATA_DIRECTORY=/durable/iris
    # Use the password file to log within the container
    命令:--password-file /durable/password/password.txt

7.3 了解层、镜像标记和构建与 运行时

在 Docker 中,正如什么是镜像?中所述,有两个重要的原则需要牢记:

  1. 镜像不可变:创建完镜像后,将无法进行修改。 您只能生成新的镜像或在镜像上添加更改。
  2. 容器镜像由层组成:每一层代表一组添加、移除或修改文件的文件系统更改。

执行 Dockerfile 中指定的指令时,新层会添加到镜像中。 这些层也将显示在镜像信息中。

考虑到这一点,务必区分 Docker 在构建时(当它从 Dockerfile 创建镜像时)和运行时(当它从该镜像启动容器时)的作用。

以下每个 Dockerfile 指令都在构建时执行:

  • COPY:将文件复制到镜像中
  • RUN:执行命令并将结果保存为新的镜像层
  • ENTRYPOINT:不改变文件系统,而是定义将在运行时启动的默认进程
  • EXPOSE:设置元数据,指示镜像打算使用哪些端口

运行时,Docker 不会重建镜像,而是在镜像上添加一个容器层。容器运行时所做的所有更改(如新文件、编辑、日志)都会进入这个临时层。

从上一个 Docker Compose 示例来看:

build: # this tells Docker to build a new image based on the one specified in the Dockerfile
  context: .        # build the image from local Dockerfile
  dockerfile: Dockerfile
image: my-modified-iris-image:latest   # give the new image a new tag to avoid overriding the base image

这些指令通过拉取基础镜像并按照 Dockerfile 中的描述进行修改,告知 Docker 创建一个名为“my-modified-iris-image:latest”的新镜像(这称为标签)。 用其他名称标记新镜像非常重要。如果我们不在新创建的镜像上放置标签,基础镜像会被新镜像覆盖。 官方镜像仍在 Docker Hub 上提供,但此本地版本会对其进行映射,并且每个引用该标签的项目现在都会不知不觉地使用包含多个新层的自定义镜像。

为了避免这种情况,请务必使用不同的标签来创建新的单独镜像,同时确保官方基础镜像干净、可重用。

7.4 源代码和初始化脚本

此时,我们应至少创建一个类,并将其放在 src/ 文件夹中。 该类将被复制到容器中,并通过 iris.script 文件导入,该文件包含在构建镜像时导入类和初始化应用程序所需的所有指令。

在项目文件夹中创建一个名为 src/DockerStepByStep 的新目录并创建以下类文件:

Class DockerStepByStep.cheers Extends%RegisteredObject
{

ClassMethod sayHi() As%Status { Set sc = $$$OKw"Hi mom!",! Return sc }

}

在项目的根目录中,创建一个名为 iris.script 的文件:

// Unexpire passwords for dev modezn"%SYS"Do##class(Security.Users).UnExpireUserPasswords("*")

// Load classes from durable sourcezn"USER"// Import classesset importPath = "/opt/irisapp/src"write"Loading classes at '", importPath, "' ...", ! set errors = ""do$System.OBJ.Import(importPath,"cuk",,.errors) if errors = 0 { write"Classes loaded successfully", ! } else { write errors, " errors occurred while loading classes!", ! }

halt

7.5 使用 Dockerfile 构建镜像

首次运行时,您可以使用以下命令从 Dockerfile 构建镜像(--build 标记会强制 Docker 从您的 Dockerfile 重建镜像):

docker-compose up --build

对于其他运行,如果 Dockerfile 未被修改,则可以简单地运行:

docker-compose up -d

开始构建镜像后,您会在终端中看到以下日志:

PS C:\InterSystems\DockerTest> docker-compose up --build
[+] Building 21.5s (13/13) FINISHED
 => [internal] load local bake definitions                                                                     0.0s
 => => reading from stdin 530B                                                                                 0.0s
 => [internal] load build definition from Dockerfile                                                           0.0s
 => => transferring dockerfile: 1.73kB                                                                         0.0s
 => [internal] load metadata for docker.io/intersystems/iris-community:latest-cd                              10.0s
 => [internal] load .dockerignore                                                                              0.0s
 => => transferring context: 2B                                                                                0.0s 
 => [1/6] FROM docker.io/intersystems/iris-community:latest-cd@sha256:93488df381f5868649e7bfc33a9083a3e86a22d  0.9s 
 => => resolve docker.io/intersystems/iris-community:latest-cd@sha256:93488df381f5868649e7bfc33a9083a3e86a22d  0.0s 
 => [internal] load build context                                                                              0.0s 
 => => transferring context: 147B                                                                              0.0s
 => [2/6] WORKDIR /opt/irisapp                                                                                 0.0s
 => [3/6] COPY src src                                                                                         0.1s 
 => [4/6] COPY iris.script .                                                                                   0.1s
 => [5/6] RUN mkdir -p /opt/irisapp/logs                                                                       0.3s
 => [6/6] RUN iris start IRIS &&     iris session IRIS < iris.script > /opt/irisapp/logs/build.log 2>&1 &&     4.5s 
 => exporting to image                                                                                         4.5s 
 => => exporting layers                                                                                        3.3s 
 => => exporting manifest sha256:3ce316cefa21a3707251c4287005a15b02e6dc0151b24baf2a82f76064792250              0.0s 
 => => exporting config sha256:00238e19edef86b29149d2eb89ff75f4d1465ba0d9a2ac4494a14d3bd3746a94                0.0s 
 => => exporting attestation manifest sha256:3579cab5c8accc7958090276deb60bd7dbbc2ecbf13af8e7fa8c4ff2dfe91028  0.0s 
 => => exporting manifest list sha256:17b969c340f57d611cc7603287cc6db50cffd696258a72b5648ece0a919676ac         0.0s 
 => => naming to docker.io/intersystems/iris-community:latest-cd                                               0.0s 
 => => unpacking to docker.io/intersystems/iris-community:latest-cd                                            0.9s 
 => resolving provenance for metadata file                                                                     0.0s 
[+] Running 3/3
 ✔ intersystems/iris-community:latest-cd  Built                                                                0.0s 
 ✔ Network dockertest_default             Created                                                              0.1s 
 ✔ Container my-iris                      Created                                                              0.2s 

在第 6/6 步中,iris.script 文件被执行到容器化的 IRIS 实例中,日志保存在路径 /opt/irisapp/logs/build.log 中。

要查看日志,可以运行以下指令:

docker exec -it my-iris cat /opt/irisapp/logs/build.log

您应当看到以下记录,这些记录会告知您类编译的结果:

Node: buildkitsandbox, Instance: IRIS

USER>

USER>

%SYS>

%SYS>

%SYS>

%SYS>

USER>

USER>

USER>

USER> Loading classes at '/opt/irisapp/src' ...

USER>

USER>

Load of directory started on 09/16/202507:46:28 Loading file /opt/irisapp/src/DockerStepByStep/cheers.cls as udl

Compilation started on 09/16/202507:46:28 with qualifiers 'cuk' Class DockerStepByStep.cheers is up-to-date. 编译在 0.005s 内成功完成。

Load finished successfully.

USER> Classes loaded successfully

USER>

USER>

在 Docker Desktop 上,您可以看到一个名为“my-modified-iris-image”的新镜像已创建,并且正在与基础官方镜像一起运行。

如果检查这些镜像,您会发现自定义镜像由 31 层组成,而不是原始镜像的 25 层。 新层与 Dockerfile 在构建时执行的指令相对应:

7.6 在容器化 IRIS 终端中运行指令

要测试这些类,您可以在容器化 IRIS 实例中激活 IRIS 终端。 为此,请执行以下指令:

docker exec -it my-iris iris session IRIS

此时,您可以使用以下命令从 USER 命名空间调用 ClassMethod:

do##class(DockerStepByStep.cheers).sayHi()

最后,您应当看到以下输出:

PS C:\InterSystems\DockerTest> docker exec -it my-iris iris session IRIS

Node: 41c3c7a9f2e4, Instance: IRIS

USER>do##class(DockerStepByStep.cheers).sayHi() Hi mom!

8. 结语和未来计划

我们已经完成了在 Docker 中运行 InterSystems IRIS 的整个周期:

  • 拉取镜像
  • 启动并配置容器
  • 使用持久化 %SYS 来持久化数据
  • 使用自己的代码和脚本构建自定义镜像

以上内容足以让您在容器化环境中试验 IRIS 并将其用于开发。

您可以访问 GitHub 仓库,其中包含最后一部分讨论的所有文件(Docker Compose、Dockerfile、iris.script 等)。

敬请期待下一篇文章!

1
0 15
文章 Claire Zheng · 九月 23, 2025 2m read

大家好! 我最近才加入 InterSystems,但发现尽管我们推出了完全免费且出色的社区版,但大家并不是十分清楚如何获取。 因此我决定编写一份指南,详细介绍获取 InterSystems IRIS 社区版的所有不同方式:

以容器形式获取 InterSystems IRIS 社区版

对于刚刚接触 InterSystems IRIS 开发的伙伴,推荐使用社区版的容器化实例,在我看来,这是最简单直接的方式。 InterSystems IRIS 社区版可以在 DockerHub 上获取;如果您有 InterSystems SSO 帐户,还可以在 InterSystems 容器注册表中获取。

在这两种情况下,您都需要使用 docker CLI 拉取所需镜像:

docker pull intersystems/iris-community:latest-em
// or
docker pull containers.intersystems.com/intersystems/iris-community:latest-em

接下来,您需要启动容器:要从容器外部与 IRIS 进行交互(例如使用管理门户),您需要发布一些端口。 以下命令将运行 IRIS 社区版容器,并发布超级服务器和 Web 服务器端口;请注意,此时不能运行其他依赖 1972 或 52773 端口的程序!

docker run --name iris -d --publish 1972:1972 --publish 52773:52773 intersystems/iris-community:latest-em

在云端获取 InterSystems IRIS 社区版

您可能想要完全避免本地安装的一系列操作,如果是这种情况,您可以借助 InterSystems IRIS 社区版的云部署实现环境搭建和运行。 所有主流云提供商均受支持;有关详细信息,请参阅我们的云合作伙伴页面。 本例将重点介绍如何在 AWS 上部署。

先在 AWS Marketplace 中找到 InterSystems IRIS 社区版:

您可以点击“查看购买选项”,并登录您的帐户查看订阅页面:

 

向下滚动,点击“订阅”,填写必填信息,然后点击“部署”,将 IRIS 社区版部署为云节点! 有关详细信息,请参阅我们关于将 InterSystems IRIS 部署到云端的文档。

以安装套件形式获取 InterSystems IRIS 社区版

如果您倾向于将 InterSystems IRIS 直接安装到自己的机器上使用,且不想处理容器,可从 InterSystems 评估服务下载适合您系统的安装套件。要下载安装套件,您需要有 InterSystems SSO 登录帐户;但好消息是,如果您有开发者社区帐户,就说明您已有 InterSystems SSO 帐户! 如果您没有此帐户,可以点击“注册新帐户”并完成后续步骤:

登录后,您应会看到以下页面;点击“下载社区版”开始下载安装套件:

 

系统将提示您填写关于所需 InterSystems IRIS 的具体版本和安装平台的信息:

 

对于大部分用例,您需要选择“InterSystems IRIS 社区版”以及您的平台可用的最新版本。 同意《服务条款》后,您便可下载安装套件! 按照平台特定文档中的安装说明进行操作,一切就搞定啦!

0
0 29
文章 Hao Ma · 十月 28, 2024 4m read

CPF merge(合并)

Automating Configuration of InterSystems IRIS with Configuration Merge

CPF merge通过合并一个人工编辑的merge file, 自动的配置新创建的iris instance, 或者修改已有的iris instance。适用于:

  • 修改iris的系统配置(cpf文件中的内容),比如系统参数,创建或者配置用户,角色,权限, 创建或者配置命名空间,数据库; 配置mirror, ECP连接等等。
  • 操作不在cpf文件中的内容,比如 CreateApplication, CreateSSLConfig 等等, 一般是在 [Action]部分实现

Caché 和早期的IRIS版本提供了manifest功能,用来做IRIS实例的配置。 Manifest很繁琐,而且各个版本的配置中有细微的区别,非常难以管理。 如今有了CPF merge, maifest的所有功能都可以在CPF merge实现, 因此manifest在新版IRIS中也就完全被替代了。

figure

执行merge

执行merge可以在操作系统命令行下执行, 如下面的例子

# 第2个参数可选,如果为空,自动使用系统当前的iris.cpf
$ iris merge iris /external/irismerge.conf /usr/irissys/iris.cpf

然而, 在执行docker run命令或者docker-compose里不用这么麻烦。 IRIS镜像提供了一个功能, 通过加入ISC_CPF_MERGE_FILE环境变量,IRIS会自动实现CPF合并。 比如下面的compose配置:

iris2024:      
        image: containers.intersystems.com/intersystems/irishealth-arm64:2024.1
        container_name: iris-a
        volumes:
            - ./iris2024:/external
        environment: 
            - TZ=CST-8
            - ISC_CPF_MERGE_FILE=/external/merge.cpf

IMPORTANT:

当使用配置合并部署容器时(如 使用合并文件部署 InterSystems IRIS 容器 中所述),只要容器在运行,ISC_CPF_MERGE_FILE(它在容器中是持久的)指定的合并文件就会持续受到更新监控,更新发生时,iris 合并命令会立即对其进行合并。这意味着您可以随时通过更新合并文件来更新容器化实例的配置,从而更容易自动重新配置容器化实例和群集。

merge文件的Example

配置IRIS参数

[config]
bbsiz=-1
globals=0,0,1024,0,0,0
routines=512
gmheap=256000

[SQL]
DefaultSchema=user
TimePrecision=6

[SqlSysDatatypes]
TIMESTAMP=%Library.PosixTime

创建用户和权限

CreateUser:Name=SQLAdmin,PasswordHash=fce110ae1f79b9d7e20367a3352efeb48ef22cc8810c4598791f3fb752eabcfe7b2d9ce75099e626b03a62fc6a146f1ca772789ebbcea276674c558c63af4f7b,9ffbbc8ef25086e4d4da87e20c6ea43e8ebb6d1ab64815aef3b1f7e8964dbd87efe68c8464a6b40865efc7d0d568c601e2a49917326dfd78197b68f1bde59db2,10000,SHA512
GrantAdminPrivilege:Grantee=SQLAdmin,Namespace=USER,AdminPriv="%DB_OBJECT_DEFINITION,%BUILD_INDEX"

CreateUser:Name=CCHUser,Password=Demo1234
GrantAdminPrivilege:Grantee=SQLAdmin,Namespace=HCC,AdminPriv="%DB_HCC,%BUILD_INDEX"

创建命名空间

# part of merge.cpf
[Actions]
CreateResource:Name=%DB_DEMO,Description="The DEMO database"
CreateDatabase:Name=DEMO,Directory=/usr/irissys/mgr/demo,Resource=%DB_DEMO,
CreateNamespace:Name=DEMO,Globals=DEMO,Interop=1

创建Web Application

[Actions]
CreateApplication:Name=/csp/demo, InboundWebServicesEnabled=1, AutheEnabled=1, DispatchClass=HCC.Interface.RestHandler, NameSpace=DEMO
CreateApplication:Name=/csp/demo,NameSpace=HCC,AutheEnabled=36,DispatchClass=HCC.Interface.RestHandler,
CreateApplication:Name=/test2,NameSpace=HCC,AutheEnabled=$$$AuthePassword+$$$AutheUnauthenticated,Enabled=1,Description="test2"
ModifyApplication:Name=/test2,MatchRoles=":%DB_HSCUSTOM:%DB_HSLIB:%DB_IRISSYS:%HS_DB_HCC:%HS_DB_HSSYS",ErrorPage=%CSP.Error

System Security Setting

System > Security Management > Authentication/Web Session Options - (security settings)

  • Allow Unauthentication access
  • Allow O/S authentication
# example
ModifyService:Name=%Service_Monitor,Enabled=1,ClientSystems=192.168.1.1
ModifyService:Name=%Service_DocDB,Enabled=1,AutheEnabled=$$$AuthePassword
ModifyService:Name=%Service_Terminal,AutheEnabled=$$$AuthePassword+$$$AutheUnauthenticated+$$$AutheOS
ModifyService:Name=%Service_Mirror,Enabled=1

其他还有更多的用法,请参见在线文档。

0
0 82
文章 Hao Ma · 十月 28, 2024 3m read

使用iris-main

iris-main是IRIS镜像的的ENTRYPOINT程序。 在Container中,ENTRYPOINT 指令允许你指定一个可执行程序或者脚本,作为容器启动后运行的主程序。这个程序会在容器启动时自动执行。

执行docker ps 命令可以看到当前container的ENTRYPOINT是什么:

hma@CNMBP23HMA demo % docker ps
CONTAINER ID   IMAGE                         COMMAND                 CREATED      STATUS      PORTS                                                               NAMES
8f31a857dc90   .../irishealth:2024.2   "/tini -- /iris-main"   3 days ago   Up 3 days   2188/tcp, 52773/tcp, 53773/tcp, 54773/tcp, 0.0.0.0:1980->1972/tcp   iris-a

hma@CNMBP23HMA demo %

我们可以用root进入container, 在根目录下查看iris-main的帮助, 或者查看在线文档的帮助-iris-main

使用的iris-main例子

以下的compose文件中, 使用了--check-caps false关闭了LInux的能力检查(capability check), 使用--key /install/iris.key加载了IRIS的license文件,并且配置了--after /install/installer.sh,它定义在container启动执行install.sh脚本。

iris-a:      
        image: containers.intersystems.com/intersystems/irishealth-arm64:2024.2
        container_name: iris-a
        hostname: irisa
        ports:
            - 1980:1972
            - 52773:52773
        environment:
            - TZ=CST-8
        volumes:
            - ./install:/install
        command: 
            --check-caps false
            --key /install/iris.key
            --after /install/installer.sh

附: iris-main的帮助

# 用root进入container, 在根目录下查看iris-main的帮助
root@irisa:/# /iris-main --help

USAGE:

   /iris-main  [--check-caps <bool>] [--monitorCPF <bool>] [--monitorKey
               <bool>] [--ISCAgentPort <integer>] [--ISCAgent <bool>] [-k
               <license key>] [-p <password file>] [-t <command>] [-c
               <command>] [-e <command>] [-a <command>] [-b <command>] [-l
               <log file>] [-s <bool>] [-u <bool>] [-d <bool>] [-i
               <instance>] [--] [--version] [-h]


Where:

   --check-caps <bool>
     Does nothing; retained for backwards compatibility

   --monitorCPF <bool>
     Monitor InterSystems IRIS CPF merge file and apply if changes detected

   --monitorKey <bool>
     Monitor InterSystems IRIS license key and update if changes detected

   --ISCAgentPort <integer>
     Set the port for ISC Agent. The default value is 2188

   --ISCAgent <bool>
     Start ISC Agent before starting IRIS. If this argument is not
     specified, it defaults to true

   -k <license key>,  --key <license key>
     Copies the InterSystems IRIS license key from the directory specified
     to the active data directory

   -p <password file>,  --password-file <password file>
     File containing desired InterSystems IRIS password

   -t <command>,  --terminate <command>
     Execute a shell command on application shutdown, after any other
     arguments are processed

   -c <command>,  --create <command>
     Execute a shell command at application startup, before any other
     arguments are processed

   -e <command>,  --exit <command>
     Execute shell commands after stopping InterSystems IRIS (via 'iris
     stop')

   -a <command>,  --after <command>
     Execute shell commands after starting InterSystems IRIS (via 'iris
     start')

   -b <command>,  --before <command>
     Execute shell commands before starting InterSystems IRIS (via 'iris
     start')

   -l <log file>,  --log <log file>
     InterSystems IRIS log file to be redirected to stdout for monitoring
     via 'docker logs'

   -s <bool>,  --nostu <bool>
     Start InterSystems IRIS with the 'nostu' option for maintenance,
     single user access mode

   -u <bool>,  --up <bool>
     Start InterSystems IRIS (via 'iris start') on container startup

   -d <bool>,  --down <bool>
     Stop InterSystems IRIS (via 'iris stop') on container shutdown

   -i <instance>,  --instance <instance>
     The InterSystems IRIS instance name to start/stop

   --,  --ignore_rest
     Ignores the rest of the labeled arguments following this flag.

   --version
     Displays version information and exits.

   -h,  --help
     Displays usage information and exits.


   iris-main

root@irisa:/#
0
0 85
文章 Hao Ma · 十月 28, 2024 2m read

把CSP.conf保存在container之外

在创建webgateway的container时,可以使用ISC_DATA_DIRECTORY=参数, 选择把CSP文保存在主机而不仅仅是container内部。如下面的例子: 使用volumnes映射了主机的./dur-wg-a目录到container的/dur目录, 而command中的ISC_DATA_DIRECTORY=/dur会讲webgateway的配置文件, log文件等保存在主机。

webgateway-apache:
        image: containers.intersystems.com/intersystems/webgateway-arm64:2024.1
        container_name: wg-tls
        hostname: wg-tls
        ports:
            - "8080:80"
            - "4433:443"
        volumes:
            - ./webgateway/csp:/external
            - ./dur-wg-a:/dur
        environment:
            - TZ=CST-8
            - ISC_CSP_CONF_FILE=/external/CSP-apache.conf
            - ISC_CSP_INI_FILE=/external/CSP-merge.ini
            - ISC_DATA_DIRECTORY=/dur

需要注意的是,这种情况下, 当配置了ISC_CSP_CONF_FILE时,比如把定制的CSP.conf放在了/dur/CSP.conf, 实际上是创建了一个link到/etc/apache2/mods-available, 而最终会链接到/etc/apache2/mods-enabled. 真正工作的CSP.conf还是在/etc/apache2/mods-enabled.

在apache2加载网站

虽然绝大多数情况WebGateway Container只用于连接IRIS,但如果在测试或者演示环境中,希望在apache2中加入自己的网站或者网页, 可以简单的参考下面的说明。

在默认的apache2.conf里面默认的定义了3个directory, <Directory /usr/share>, <Directory /usr/share>,<Directory /var/www/>,而在sites-enabled里面是这么配置的

root@ac6fdedbac6b:/etc/apache2# cat sites-enabled/000-default.conf
<VirtualHost *:80>
	ServerAdmin webmaster@localhost
	DocumentRoot /var/www/html
	ErrorLog ${APACHE_LOG_DIR}/error.log
	CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
root@ac6fdedbac6b:/etc/apache2#

因为000-default.conf是默认生效的配置文件,因此把自动的网站放在/拷贝到/var/www/html目录是最简单的方案。 注意您的网站如果有js或者其他可执行的文件, 网站目录和文件的权限应该是755.

0
0 89
文章 Hao Ma · 十月 28, 2024 7m read

上一篇文章使用人工配置的方法简单的配置了webgateway container. 接下来来介绍如何在docker-compose里做自动化部署。

先总结我们要做的事情:

  1. 配置到IRIS的连接。定义连接的iris的IP地址或者DNS, 以及连接的用户名密码 以及其他的对默认值的修改。
  2. 配置apache2的配置文件,保证到IRIS的HTTP请求能发送给CSP Webgateway。
  3. 很多时候,用户会希望使用HTTPS访问IRIS,因此需要在apache2上支持TLS。

这些是最基本的功能。除此之外, 用户还可能会要求建立WebGateway到IRIS的TLS连接,或者在Apache2部署自己的网页等等。后面的文章会一一介绍。

配置CSP.ini

上一篇文章中,我通过Webgateway管理页面定义了Webgateway到IRIS的连接,其实是定义了webgateway的配置文件CSP.ini。 无论WebServer是什么类型,IIS,Apache, Nginx, CSP.ini的都是一样的。在Linux中, CSP.ini位于/opt/webgateway/bin目录。

InterSystems提供了一个工具叫 CSP merge。 简单的说,就是可以定义一个被合并的文件, webgateway运行时会不停的扫描这个文件,发现有内容的修改,就把修改后的配置项合并到工作中的CSP.ini中去。 具体的内容您可以参见在线文档-CSP.ini merge feature

CSP merge的merge文件不需要定义所有的配置项,理论上,只定义需要修改的部分就可以。但注意在一个配置部分(section)内部, 配置项之间是有关系的,单独定义其中的一项配置是不会生效的。

比如, 这是原始的CSP.ini中的LOCAL服务器的配置部分:

因此,merge文件里正确的LOCAL部分是:

[LOCAL]
Ip_Address=127.0.0.1
TCP_Port=1972
Minimum_Server_Connections=3
Maximum_Session_Connections=6
Connection_Security_Level=0  ; 0:password, 1:kerberos...
Username=CSPSystem
Password=]]]U1lT
SSLCC_Protocol_Min=16
SSLCC_Protocol_Max=32
SSLCC_Key_Type=2
SSLCC_Cipher_Suites=ALL:!aNULL:!eNULL:!EXP:!SSLv2
SSLCC_Cipher_Suites_1_3=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

如果您只希望修改Ip_Address, 因此在被合并的文件中定义

[LOCAL]
Ip_Address=192.168.1.2
TCP_Port=1972

而这样的定义会 造成加载失败。也就是说,CSP merge需要合并完整的Section。上面的例子中定义了这个服务器的地址,但没有定义连接它的账户和密码,这是不能接受的。

我习惯用比较完整的配置文件做合并,下面是一个例子。文件名可以任意,这里我命名为CSP-merge.ini:

[APP_PATH_INDEX]
/=Enabled
/csp=Enabled

[APP_PATH:/]
Default_Server=LOCAL
Alternative_Server_0=1~~~~~~LOCAL

[APP_PATH:/csp]
Default_Server=LOCAL
Alternative_Server_0=1~~~~~~LOCAL

[SYSTEM]
IRISCONNECT_LIBRARY_PATH=/opt/webgateway/bin
System_Manager=*.*.*.*
SM_Timeout=28800
Server_Response_Timeout=60
No_Activity_Timeout=86400
Queued_Request_Timeout=60
Default_Server=LOCAL
RELOAD=1  ; reload csp gateway setting in one minute

[SYSTEM_INDEX]
LOCAL=Enabled

[LOCAL]
Ip_Address=iris-a
TCP_Port=1972
Minimum_Server_Connections=3
Maximum_Session_Connections=6
Connection_Security_Level=0  ; 0:password, 1:kerberos...
Username=CSPSystem
Password=]]]U1lT
SSLCC_Protocol_Min=16
SSLCC_Protocol_Max=32
SSLCC_Key_Type=2
SSLCC_Cipher_Suites=ALL:!aNULL:!eNULL:!EXP:!SSLv2
SSLCC_Cipher_Suites_1_3=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

Tip1: [SYSTEM]中配置RELOAD=1, 可以让webgateway setting每分钟检查一次csp-merge.ini, 如果有修改,会实时的执行合并。

Tip2: 想了解更多的CSP.ini的配置项的内容,请访问在线文档- Define a Server Access Profile for Your InterSystems IRIS Instance

Tip3: 在生产系统中,定义SYSTEM部分的: System_Manager=*.*.*.*是不安全的。

自动部署CSP合并文件

简单的说明: CSP-merge.ini文件位于host中的./webgateway文件夹,通过volumes映射到container的/external文件夹。 通过定义环境变量ISC_CSP_INI_FILE,docker启动时会执行CSP文件的合并。

 webgateway-apache:
      image: containers.intersystems.com/intersystems/webgateway-arm64:2024.1
      container_name: wg-apache
      hostname: wg-apache
      ports:
          - "8080:80"
      volumes:
          - ./webgateway:/external
      environment:
          - TZ=CST-8 
          - ISC_CSP_INI_FILE=/external/CSP-merge.ini

后面介绍如何配置apache2访问IRIS服务地址。

配置Apache2

配置apache2可以参考apache2的主页面,配置文件的结构如下:

apache2的主配置文件/etc/apache2/apache2.conf包含(includes)了其他自子目录下的被enabled的配置文件,结构如下图:

root@wg-a:/etc/apache2# cat apache2.conf
...
# It is split into several files forming the configuration hierarchy outlined
# below, all located in the /etc/apache2/ directory:
#
#	/etc/apache2/
#	|-- apache2.conf
#	|	`--  ports.conf
#	|-- mods-enabled
#	|	|-- *.load
#	|	`-- *.conf
#	|-- conf-enabled
#	|	`-- *.conf
# 	`-- sites-enabled
#	 	`-- *.conf

CSP.conf是怎么工作的

InterSystems Webgateway是apache2的一个工作的module. 它的配置文件是/etc/apache2/mods-available/CSP.conf。在webgateway container启动时,apache2会执行这个module的生效(enable), 这时会在/etc/apache2/mods-enabled目录中创建一个链接到原始文件。

默认的CSP.conf的内容如下:

root@wg-a:/etc/apache2# cat /etc/apache2/mods-available/CSP.conf

CSPModulePath "${ISC_PACKAGE_INSTALLDIR}/bin/"
CSPConfigPath "${ISC_PACKAGE_INSTALLDIR}/bin/"

<Location "/csp/bin/Systems/">
    SetHandler csp-handler-sa
</Location>
<Location "/csp/bin/RunTime/">
    SetHandler csp-handler-sa
</Location>

<Directory "${ISC_PACKAGE_INSTALLDIR}/bin/">
    AllowOverride None
    Options None
    Require all granted
    <FilesMatch "\.(log|ini|pid|exe)$">
         Require all denied
    </FilesMatch>
</Directory>
root@wg-a:/etc/apache2#

修改CSP.conf

以上的CSP.conf中只有使用CSP module的内容,而并没有访问IRIS的URL的部分。 , 需要一个个的添加要发送到webgateway模块的URL。必须的有这几个:/csp, /api,/isc, 其他还包括您自己定义的URL, 也需要创建对应的<Location>

以下是要添加的内容:

# 添加要发送给IRIS的URL
<Location "/csp">CSP On</Location>
<Location "/api">CSP On</Location>
<Location "/isc">CSP On</Location>
<Location "/customerURL">CSP On</Location>

Tip1: 如果您确认此container只用于连接IRIS, 您可以定义<Location />将所有的请求发送给webgateway模块。但注意访问http://localhost:8080时会返回错误404,apache2原本会把请求发到/var/www/html/index.html,修改后会把这个请求发给IRIS。

自动部署CSP.conf的修改

配置container是新的CSP.conf通过SC_CSP_CONF_FILE加入,这个不是合并, 是整个覆盖替换原始的配置文件。以下是compose文件的示意,同样,CSP-apache.conf文件位于host的./webgateway文件夹,通过volumes映射到container的/external文件夹。

webgateway-apache:
      image: containers.intersystems.com/intersystems/webgateway-arm64:2024.1
      container_name: wg-apache
      hostname: wg-apache
      ports:
          - "8080:80"
      volumes:
          - ./webgateway:/external
      environment:
          - TZ=CST-8 
          - ISC_CSP_INI_FILE=/external/CSP-merge.ini
          - ISC_CSP_CONF_FILE=/external/CSP-apache.conf

要修改CSP.conf, 如果要在container外面修改,需要修改ISC_CONF-FILE的内容, 然后重启container. /dur里面的CSP.conf不能改, 改了保存后会自动改回来。

配置Apache2的TLS

方法1. 用命令开启

配置HTTPS访问apache2最简单的方式打开apache2内置的ssl模块,并使default-ssl.conf生效。如下面的脚本文件中的操作:

root@wg-a:/etc/apache2# a2enmod ssl 
root@wg-a:/etc/apache2# ls -l mods-enabled/ssl*
lrwxrwxrwx 1 root root 26 Oct  9 09:00 mods-enabled/ssl.conf -> ../mods-available/ssl.conf
lrwxrwxrwx 1 root root 26 Oct  9 09:00 mods-enabled/ssl.load -> ../mods-available/ssl.load
root@wg-a:/etc/apache2# a2ensite default-ssl
Enabling site default-ssl.
To activate the new configuration, you need to run:
  service apache2 reload
root@wg-a:/etc/apache2# service apache2 reload
 * Reloading Apache httpd web server apache2                                                                                            *
root@wg-a:/etc/apache2#

方法2. 设置自己的配置

因为已经Copy了一个CSP.conf进去,其实可以在这个文件里配置SSL的部分, 好处是不用单独写一个文件, 坏处是从维护的角度,把CSP module的配置和SSL的配置写在一个文件不是很合理。

# 加入下部分到CSP.conf, 其中使用了自己的TLS配置,而不是openssl的证书和key. 
LoadModule ssl_module /usr/lib/apache2/modules/mod_ssl.so
<VirtualHost *:443>
    SSLEngine on
    SSLCertificateFile "/external/cert/sslwebcert.crt"
    SSLCertificateKeyFile "/external/cert/sslwebkey.key"
</VirtualHost>

或者使用ssl mod的 conf

<VirtualHost _default_:443>
		ServerAdmin webmaster@localhost
		DocumentRoot /var/www/html
		ErrorLog ${APACHE_LOG_DIR}/error.log
		CustomLog ${APACHE_LOG_DIR}/access.log combined
		SSLEngine on
		SSLCertificateFile	/etc/ssl/certs/ssl-cert-snakeoil.pem
		SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
		<FilesMatch "\.(cgi|shtml|phtml|php)$">
				SSLOptions +StdEnvVars
		</FilesMatch>
		<Directory /usr/lib/cgi-bin>
				SSLOptions +StdEnvVars
		</Directory>
</VirtualHost>
0
0 122
文章 Hao Ma · 十月 28, 2024 6m read

IRIS image下载

参考:下载Images的在线文档

https://containers.intersystems.com网站上获得可以下载的InterSystems的各种docker镜像。如果只是安装Community版本, 不需要注册。如果是下载安装正式的版本,需要在网站注册,然后获得Login Token登陆。

#;这一部有可能需要科学上网,否则无法正常登陆

hma@CNMBP23HMA ~ % docker login -u="hma" -p="k8zIqpoafIUaViP2BA4gCZdcC4EeKyb0svSjnyVtcWMb" containers.intersystems.com
WARNING! Using --password via the CLI is insecure. Use --password-stdin.
Login Succeeded

# pull iris image,webgateway,Passhash, arbiter, etc.
hma@CNMBP23HMA ~ % docker pull containers.intersystems.com/intersystems/healthconnect-arm64:latest-cd
hma@CNMBP23HMA ~ % docker pull containers.intersystems.com/intersystems/webgateway-arm64:latest-cd
...

Tips

  • 下载社区(Community)版本的镜像不用在网站注册,使用时也不需要安装license。社区版内置内置了一个13个月的license。而正式版本IRIS Continer安装需要从InterSystems处获得IRIS docker版的专用license。

  • 标记latest-cd(Continuous delivery)latest-em(Extended maintenance), latest-preview是最新的"持续交付"版本, "扩展维护"版本,以及"开发预览版"。 您也可以选择指定专门的版本,比如当前最新的GA版本2024.2。同时,如果硬件是ARM芯片,请选择带有“-arm64"后缀的版本。

  • WebGateway-nginx是nginx服务器的版本,而WebGateway镜像内置了apache2服务。

简单的搭建测试环境

我要使用的iris 2024的版本,其中再没有之前的内置的PWS(Private Web Server), 也就是说您当前以及无法从http://localhost:52773/csp/sys/UtilHome.csp登录管理门户了。因此我用docker-compose来创建下面的例子。docker-compose用来编排多个container共同工作。它自动的创建一个单独的docker network, 其中的所有service, 也就是docker container可以通过container name通信。

如果是简单的测试环境, 可以直接用docker run运行IRIS Container。 我们先来run一个最简单的社区版:

compose.yaml

services:
    iris-a:      
        image: containers.intersystems.com/intersystems/irishealth-community-arm64:2024.2
        container_name: iris-a
        hostname: irisa
        ports:
            - 1980:1972
            - 52773:52773
        environment:
            - TZ=CST-8
    webgateway-apache:
        image: containers.intersystems.com/intersystems/webgateway-arm64:2024.1
        container_name: wg-apache
        hostname: wg-apache
        ports:
            - "8080:80"
        environment:
            - TZ=CST-8

说明两点: 1. 在IRIS2024中52773端口已经无法使用,所以不需要再被映射到主机。 2. TZ=CST-8是把container的时区设置为上海。

运行后可以看到两个container都已经工作

hma@CNMBP23HMA demo % docker-compose up -d
[+] Running 3/3
 &#x2714; Network demo_default  Created                                                                                         0.0s
 &#x2714; Container wg-apache   Started                                                                                         0.0s
 &#x2714; Container iris-a      Started                                                                                         0.0s
hma@CNMBP23HMA demo % docker ps
CONTAINER ID   IMAGE                                                                        COMMAND                 CREATED         STATUS         PORTS                                                               NAMES
cfa4cc730c14   containers.intersystems.com/intersystems/irishealth-community-arm64:2024.2   "/tini -- /iris-main"   6 seconds ago   Up 5 seconds   2188/tcp, 52773/tcp, 53773/tcp, 54773/tcp, 0.0.0.0:1980->1972/tcp   iris-a
63e983d90034   containers.intersystems.com/intersystems/webgateway-arm64:2024.1             "/startWebGateway"      6 seconds ago   Up 5 seconds   0.0.0.0:8080->80/tcp, 0.0.0.0:4433->443/tcp                         wg-apache
hma@CNMBP23HMA demo %

查看iris container

这时,虽然还无法登录iris的管理门户,您可以使用docker exec进入iris container查看iris实例已运行。 注意两点:

  1. 默认登录的用户是irisowner
  2. IRIS的安装路径是/usr/irissys.
hma@CNMBP23HMA installer_cch % docker ps
CONTAINER ID   IMAGE                                                              COMMAND                 CREATED         STATUS         PORTS                                                                              NAMES
59e2424757db   containers.intersystems.com/intersystems/irishealth-arm64:2024.1   "/tini -- /iris-main"   6 seconds ago   Up 5 seconds   0.0.0.0:1972->1972/tcp, 2188/tcp, 53773/tcp, 0.0.0.0:52773->52773/tcp, 54773/tcp   iris
hma@CNMBP23HMA installer_cch % docker exec -it iris bash
irisowner@59e2424757db:~$ iris list

Configuration 'IRIS'   (default)
	directory:    /usr/irissys
	versionid:    2024.1.0.263.0
	datadir:      /usr/irissys
	conf file:    iris.cpf
	status:       running, since Wed Oct 23 12:32:45 2024
	SuperServers: 1972
	state:        warn
	product:      InterSystems IRISHealth
irisowner@59e2424757db:~$ iris session iris
Node: 59e2424757db, Instance: IRIS

USER>halt
irisowner@59e2424757db:~$

查看Webgateway Container

  1. 从浏览器打开 http://localhost:8080, 可以看到apache2的主页面。
  2. 访问http://localhost:8080/csp/bin/Systems/Module.cxw?CSPSYS=0&CSPSYSreferer=_CSP.Portal.Home.zen,可以进入Webgateway的配置页面。 这里一定注意:访问http://localhost:8080/csp/bin/Systems/Module.cxw会得到500错误。当前状态下一定要带着参数访问这个网址。
  3. 配置webgateway到iris的连接:在当前页面,你需要设置。
    • Server Local的IP/DNS和Port:这里是iris container的名字iris-a,和iris-a container的superserver端口1972
    • 登录iris的账户密码:CSPSystem, SYS

保存设置,然后在"Test Server Connection"页面测试连接,你将看到连接成功的结果。

  1. 尽量webgateway已经成功连接了IRIS, 但配置还没有完。要成功访问IRIS管理页面,你需要修改一个apache2的配置文件CSP.conf

    • 使用docker exec -it wg-apache bash进入container.
    • 修改/etc/apache2/mods-available/CSP.conf配置文件,如下:
    # 原始文件的内容
    
    CSPModulePath "${ISC_PACKAGE_INSTALLDIR}/bin/"
    CSPConfigPath "${ISC_PACKAGE_INSTALLDIR}/bin/"
    
    <Location "/csp/bin/Systems/">
        SetHandler csp-handler-sa
    </Location>
    <Location "/csp/bin/RunTime/">
        SetHandler csp-handler-sa
    </Location>
    <Directory "${ISC_PACKAGE_INSTALLDIR}/bin/">
        AllowOverride None
        Options None
        Require all granted
        <FilesMatch "\.(log|ini|pid|exe)$">
             Require all denied
        </FilesMatch>
    </Directory>
    
    # 自己添加的内容
    <Location "/csp">
        CSP On
    </Location>
    <Location "/api">
        CSP On
    </Location>
    <Location "/isc">
        CSP On
    </Location>
    
    • 用命令行service apache2 restart重启apache2, 或者从container里退出重启wg-apache container.
    • 从浏览器访问http://localhost:8080/csp/sys/UtilHome.csp, 您应该已经可以成功访问IRIS了。

总结

虽然题目是'简单的搭建测试环境', 但实际上还是有非常多的步骤,主要是集中在webgateway到IRIS的连接上。 如果您熟悉docker-compose,您知道这样人工的配置一个container是不合适的。而后面的章节我会专门有一章节如何在docker-compose里自动配置webgateway。之所以还要介绍webgateway的人工配置步骤,是因为这些知识是自动配置webgateway的背景知识,而且在做debug时非常关键。

另外,后面我还会介绍webgateay-nginx的配置。

0
0 195
文章 Hao Ma · 十月 28, 2024 1m read

我在3年前写过同样内容的文章。随着IRIS版本的更新,安装的细节有了些变化,而且,尤其是2024年以后的版本不再使用PWS(Private Web Server), 安装最新版本的IRIS通常同时要安装一个外部的Web服务器,Apache或者nginx。 另外, 大家对自动部署的需要越来越多,因此我也会在下面的内容里面包括自动部署,配置iris, 安装软件等等内容。希望给各位一个基本完整的介绍。

内容列表如下:

基础篇

  • IRIS images的下载和docker run
  • apache-webgateway container到iris的连接
  • nginx-webgateway container到iris的连接
  • iris-main和在container外保存iris数据
  • 配置iris的新方法:CPF merge ...

随时更新

0
0 147
文章 Michael Lei · 九月 27, 2024 8m read

在这一系列文章中,我想向大家介绍并探讨使用 InterSystems 技术和 GitLab 进行软件开发可以采用的几种方式。 我将介绍以下主题:

  • Git 101
  • Git 流程(开发流程)
  • GitLab 安装
  • GitLab 工作流
  • 持续交付
  • GitLab 安装和配置
  • GitLab CI/CD

第一篇文章中,我们介绍了 Git 基础知识、深度理解 Git 概念对现代软件开发至关重要的原因,以及如何使用 Git 开发软件。

第二篇文章中,我们介绍了 GitLab 工作流 – 一个完整的软件生命周期流程,并介绍了持续交付。

第三篇文章中,我们介绍了 GitLab 安装和配置以及将环境连接到 GitLab

在这篇文章中,我们将介绍编写 CD 配置。

计划

环境

首先,我们需要多个环境以及与之对应的分支:

环境分支交付有权提交的角色有权合并的角色
测试master自动开发者、所有者开发者、所有者
预生产preprod自动所有者
生产prod半自动(按下按钮进行交付)

所有者

开发周期

作为示例,我们将使用 GitLab 流程开发一个新功能,并使用 GitLab CD 进行交付。

  1. 在功能分支中开发功能。
  2. 对功能分支进行审查并将其合并到 master 分支中。
  3. 一段时间(合并了多个功能)后,将 master 分支合并到 preprod 分支中
  4. 一段时间(用户测试等)后,将 preprod 分支合并到 prod 分支中

具体如下图所示(我用草图标出了我们需要为 CD 开发的部分):

  1. 开发和测试
    • 开发者将新功能的代码提交到单独的功能分支中
    • 功能稳定后,开发者将功能分支合并到 master 分支中
    • 来自 master 分支的代码被交付到测试环境,在其中进行加载和测试
  2. 交付到预生产环境
    • 开发者创建从 master 分支到 preprod 分支的合并请求
    • 仓库所有者在一段时间后批准合并请求
    • 来自 preprod 分支的代码被交付到预生产环境
  3. 交付到生产环境
    • 开发者创建从 preprod 分支到 prod 分支的合并请求
    • 仓库所有者在一段时间后批准合并请求
    • 仓库所有者按下“部署”按钮
    • 来自 prod 分支的代码被交付到生产环境

也可以用示意图形式表示此流程:

应用程序

应用程序由两部分组成:

  • 在 InterSystems 平台上开发的 REST API
  • 客户端 JavaScript web 应用程序

阶段

通过上面的计划,我们可以确定需要在持续交付配置中定义的阶段:

  • 加载 – 将服务器端代码导入 InterSystems IRIS
  • 测试 – 测试客户端和服务器代码
  • 封装 – 构建客户端代码
  • 部署 – 使用 Web 服务器“发布”客户端代码

以下是它在 gitlab-ci.yml 配置文件中的样式:

stages:
  - load
  - test
  - package
  - deploy

脚本

加载

下面我们来定义脚本。 脚本文档。 我们先来定义用于加载服务器端代码的脚本 load server

load server:
  environment:
    name: test
    url: http://test.hostname.com
  only:
    - master
  tags:
    - test
  stage: load
  script: csession IRIS "##class(isc.git.GitLab).load()"

脚本会执行哪些操作?

  • load server 是脚本名称
  • 接下来,我们来描述此脚本运行的环境
  • only: master – 告知 GitLab 此脚本仅应在向 master 分支进行提交时运行
  • tags: test 指定此脚本仅应在具有 test 标签的运行程序上运行
  • stage 指定脚本的阶段
  • script 定义要执行的代码 在本例中,我们从 isc.git.GitLab 类调用类方法 load

重要说明

对于 InterSystems IRIS,请将 csession 替换为 iris session

对于 Windows,请使用:irisdb -s ../mgr -U TEST "##class(isc.git.GitLab).load()

现在,我们来编写相应的 isc.git.GitLab 类。 此类中的所有入口点如下所示:

ClassMethod method()
{
    try {
        // code
        halt
    } catch ex {
        write !,$System.Status.GetErrorText(ex.AsStatus()),!
        do $system.Process.Terminate(, 1)
    }
}

请注意,可以通过两种方式结束此方法:

  • 停止当前进程 – 在 GitLab 中注册为成功完成
  • 调用  $system.Process.Terminate – 异常终止进程,GitLab 将此情况注册为错误

因此,加载代码如下:

/// Do a full load
/// do ##class(isc.git.GitLab).load()
ClassMethod load()
{
    try {
        set dir = ..getDir()
        do ..log("Importing dir " _ dir)
        do $system.OBJ.ImportDir(dir, ..getExtWildcard(), "c", .errors, 1)
        throw:$get(errors,0)'=0 ##class(%Exception.General).%New("Load error")
    halt
} catch ex {
    write !,$System.Status.GetErrorText(ex.AsStatus()),!
    do $system.Process.Terminate(, 1)
}

}

调用了两个实用方法:

  • getExtWildcard – 获取相关文件扩展名列表
  • getDir – 获取仓库目录

如何获取目录?

执行脚本时,GitLab 会先指定很多环境变量。 其中一个环境变量是 CI_PROJECT_DIR – 克隆仓库以及运行作业位置的完整路径。 我们可以通过 getDir 方法轻松获取:

ClassMethod getDir() [ CodeMode = expression ]
{
##class(%File).NormalizeDirectory($system.Util.GetEnviron("CI_PROJECT_DIR"))
}


测试

以下是测试脚本:

load test:
  environment:
    name: test
    url: http://test.hostname.com
  only:
    - master
  tags:
    - test
  stage: test
  script: csession IRIS "##class(isc.git.GitLab).test()"
  artifacts:
    paths:
      - tests.html

有哪些更改? 当然是名称和脚本代码,但还添加了工件。 工件是作业成功完成后附加到作业的文件和目录列表。 本例中,测试完成后,我们可以生成重定向到测试结果的 HTML 页面,并使其可以通过 GitLab 访问。

请注意,加载阶段有很多复制粘贴的内容 – 环境是相同的,脚本部分(例如环境)可以单独标记并附加到脚本。 我们来定义测试环境:

.env_test: &env_test
  environment:
    name: test
    url: http://test.hostname.com
  only:
    - master
  tags:
    - test

现在,我们的脚本如下:

load test:
  <<: *env_test
  script: csession IRIS "##class(isc.git.GitLab).test()"
  artifacts:
    paths:
      - tests.html

接下来,我们使用 UnitTest 框架执行测试。

/// do ##class(isc.git.GitLab).test()
ClassMethod test()
{
    try {
        set tests = ##class(isc.git.Settings).getSetting("tests")
        if (tests'="") {
            set dir = ..getDir()
            set ^UnitTestRoot = dir
        $$$TOE(sc, ##class(%UnitTest.Manager).RunTest(tests, "/nodelete"))
        $$$TOE(sc, ..writeTestHTML())
        throw:'..isLastTestOk() ##class(%Exception.General).%New("Tests error")
    }
    halt
} catch ex {
    do ..logException(ex)
    do $system.Process.Terminate(, 1)
}

}

本例中,测试设置是相对于存储单元测试的仓库根目录的路径。 如果此处为空,则跳过测试。 writeTestHTML 方法用于输出重定向到测试结果的 html:

ClassMethod writeTestHTML()
{
    set text = ##class(%Dictionary.XDataDefinition).IDKEYOpen($classname(), "html").Data.Read()
    set text = $replace(text, "!!!", ..getURL())
set file = ##class(%Stream.FileCharacter).%New()
set name = ..getDir() _  "tests.html"
do file.LinkToFile(name)
do file.Write(text)
quit file.%Save()

}

ClassMethod getURL() { set url = ##class(isc.git.Settings).getSetting("url") set url = url _ $system.CSP.GetDefaultApp("%SYS") set url = url_"/%25UnitTest.Portal.Indices.cls?Index="_ $g(^UnitTest.Result, 1) _ "&$NAMESPACE=" _ $zconvert($namespace,"O","URL") quit url }

ClassMethod isLastTestOk() As %Boolean { set in = ##class(%UnitTest.Result.TestInstance).%OpenId(^UnitTest.Result) for i=1:1:in.TestSuites.Count() { #dim suite As %UnitTest.Result.TestSuite set suite = in.TestSuites.GetAt(i) return:suite.Status=0 $$$NO } quit $$$YES }

XData html { <html lang="en-US"> <head> <meta charset="UTF-8"/> <meta http-equiv="refresh" content="0; url=!!!"/> <script type="text/javascript"> window.location.href = "!!!" </script> </head> <body> If you are not redirected automatically, follow this <a href='!!!'>link to tests</a>. </body> </html> }

封装

我们的客户端是一个简单的 HTML 页面:

<html>
<head>
<script type="text/javascript">
function initializePage() {
  var xhr = new XMLHttpRequest();
  var url = "${CI_ENVIRONMENT_URL}:57772/MyApp/version";
  xhr.open("GET", url, true);
  xhr.send();
  xhr.onloadend = function (data) {
    document.getElementById("version").innerHTML = "Version: " + this.response;
  };

var xhr = new XMLHttpRequest(); var url = "${CI_ENVIRONMENT_URL}:57772/MyApp/author"; xhr.open("GET", url, true); xhr.send(); xhr.onloadend = function (data) { document.getElementById("author").innerHTML = "Author: " + this.response; }; } </script> </head> <body onload="initializePage()"> <div id = "version"></div> <div id = "author"></div> </body> </html>

要进行构建,需要将 ${CI_ENVIRONMENT_URL} 替换为其值。 当然,实际应用程序可能需要 npm,但此处仅为了举例说明。 脚本如下:

package client:
  <<: *env_test
  stage: package
  script: envsubst < client/index.html > index.html
  artifacts:
    paths:
      - index.html

部署

最后,我们将 index.html 部署到 Web 服务器根目录,以部署客户端。

deploy client:
  <<: *env_test
  stage: deploy
  script: cp -f index.html /var/www/html/index.html

就是这些!

多个环境

如果您需要在多个环境中执行相同(相似)的脚本,应该如何操作? 脚本部分也可以是标签,因此下面给出了在测试和预生产环境中加载代码的示例配置:

stages:
  - load
  - test

.env_test: &env_test environment: name: test url: http://test.hostname.com only: - master tags: - test

.env_preprod: &env_preprod environment: name: preprod url: http://preprod.hostname.com only: - preprod tags: - preprod

.script_load: &script_load stage: load script: csession IRIS "##class(isc.git.GitLab).loadDiff()"

load test: <<: *env_test <<: *script_load

load preprod: <<: *env_preprod <<: *script_load

通过这种方式,我们便无需复制粘贴代码。

有关完整的 CD 配置,请参阅此处。 该配置遵循在测试、预生产和生产环境之间移动代码的原始计划。

结论

可以将持续交付配置为自动执行任何所需的开发工作流。

链接

后续内容

在下一篇文章中,我们将创建利用 InterSystems IRIS Docker 容器的 CD 配置。

0
0 104
文章 Michael Lei · 九月 26, 2024 4m read

在这一系列文章中,我想向大家介绍并探讨使用 InterSystems 技术和 GitLab 进行软件开发可以采用的几种方式。 我将介绍以下主题:

  • Git 101
  • Git 流程(开发流程)
  • GitLab 安装
  • GitLab 工作流
  • 持续交付
  • GitLab 安装和配置
  • GitLab CI/CD

第一篇文章中,我们介绍了 Git 基础知识、深度理解 Git 概念对现代软件开发至关重要的原因,以及如何使用 Git 开发软件。

第二篇文章中,我们介绍了 GitLab 工作流 – 一个完整的软件生命周期流程,并介绍了持续交付。

在这篇文章中,我们将探讨:

  • GitLab 安装和配置
  • 将环境连接到 GitLab

GitLab 安装

我们将在本地安装 GitLab。 可以通过多种方式安装 GitLab – 通过源代码、软件包安装,以及在容器中安装。 我不会在这里详细介绍所有步骤,请参阅相关指南。 但仍需要注意几点:

前提条件:

  • 单独的服务器 – 由于 GitLab 属于 Web 应用程序,并且需要占用大量资源,最好在单独的服务器上运行
  • Linux
  • (可选,但强烈建议采用)域 – 运行页面和保护整个安装时需要

配置

首先,您可能需要发送包含通知的电子邮件

接下来,建议安装 Pages。 正如我们在上一篇文章中所讨论的 – 可以将脚本中的工件上传到 GitLab。 用户可以下载这些工件,但能够直接在浏览器中打开工件将非常有用,为此我们需要使用页面。

需要使用页面的原因:

由于 html 页面会在加载时重定向,可以使用 html 页面将用户重定向到我们需要的位置。 例如,下列代码生成的 html 页面会将用户重定向到上次执行的单元测试(生成 html 时):

ClassMethod writeTestHTML()
{
  set text = ##class(%Dictionary.XDataDefinition).IDKEYOpen($classname(), "html").Data.Read()
  set text = $replace(text, "!!!", ..getURL())

set file = ##class(%Stream.FileCharacter).%New() set name = "tests.html" do file.LinkToFile(name) do file.Write(text) quit file.%Save() }

ClassMethod getURL() { set url = "http://host:57772" set url = url _ $system.CSP.GetDefaultApp("%SYS") set url = url_"/%25UnitTest.Portal.Indices.cls?Index="_ $g(^UnitTest.Result, 1) _ "&$NAMESPACE=" _ $zconvert($namespace,"O","URL") quit url }

XData html { <html lang="en-US"> <head> <meta charset="UTF-8"/> <meta http-equiv="refresh" content="0; url=!!!"/> <script type="text/javascript">window.location.href = "!!!"</script> </head> <body> If you are not redirected automatically, follow this <a href='!!!'>link to tests</a>. </body> </html> }

我使用页面时遇到了错误(浏览工件时出现 502 错误) - 解决方法

 

将环境连接到 GitLab

要运行 CD 脚本,需要使用环境,即配置好的用于运行应用程序的服务器。 假设有一个安装了 InterSystems 产品(例如 InterSystems IRIS,但也可以使用 Caché 和 Ensemble)的 Linux 服务器,可以通过以下步骤将环境连接到 GitLab:

  1. 安装 GitLab 运行程序
  2. 在 GitLab 中注册运行程序
  3. 允许运行程序调用 InterSystems IRIS
有关安装 GitLab 运行程序的

重要说明 - 安装 GitLab 运行程序后请勿克隆服务器。否则,结果将不可预测,并且大多数情况下的结果都不尽如人意。

在 GitLab 中注册运行程序

运行初始程序后:

sudo gitlab-runner register

您会看到多个提示,大部分步骤都非常简单,但有几步比较复杂:

请输入用于此运行程序的 gitlab-ci 令牌

有多个令牌可用:

  • 一个令牌用于整个系统(在管理设置中提供)
  • 一个令牌用于每个项目(在项目设置中提供)

由于您连接运行程序是为特定项目运行 CD,需要指定此项目的令牌。

请输入此运行程序的 gitlab-ci 标签(以逗号分隔):

在 CD 配置中,您可以筛选针对具体标签运行的脚本。 因此,在最简单的情况下,请指定一个将作为环境名称的标签。

请输入执行器:ssh、docker+machine、docker-ssh+machine、kubernetes、docker、parallels、virtualbox、docker-ssh、shell:
docker

如果您使用的是没有 docker 的普通服务器,请选择 shell。我们将在后续部分讨论 docker。

允许运行程序调用 InterSystems IRIS

将运行程序连接到 GitLab 后,我们需要允许运行程序与 InterSystems IRIS 交互,为此:

  1. gitlab-runner 用户应能够调用会话。 为此,请将该用户添加到 cacheusr 组:
    • usermod -a -G cacheusr gitlab-runner
  2. 在 InterSystems IRIS 中创建gitlab-runner 用户,并为其指定相应角色以执行 CD 任务(写入到数据库等)
  3. 允许进行操作系统级身份验证

对于 2 和 3,可以采用其他方式,例如传递用户名/密码,但我认为操作系统身份验证是更好的选择。

结论

在本部分中:

  • 我们安装了 GitLab
  • 将环境连接到 GitLab

后续内容

在下一部分中,我们将编写持续交付配置。

0
0 102
文章 Michael Lei · 九月 26, 2024 7m read

在这一系列文章中,我想向大家介绍并探讨使用 InterSystems 技术和 GitLab 进行软件开发可以采用的几种方式。 我将介绍以下主题:

  • Git 101
  • Git 流程(开发流程)
  • GitLab 安装
  • GitLab 工作流
  • 持续交付
  • GitLab 安装和配置
  • GitLab CI/CD

上一篇文章中,我们介绍了 Git 基础知识、深度理解 Git 概念对现代软件开发至关重要的原因,以及如何使用 Git 开发软件。 我们的侧重点仍是软件开发的实现部分,但本部分会介绍:

  • GitLab 工作流 - 从想法到用户反馈的完整软件生命周期流程
  • 持续交付 – 软件工程方式,团队通过这种方式在短周期内制作软件,从而确保软件可以随时实现可靠发布。 它的目的是更快速、更频繁地构建、测试和发布软件。

GitLab 工作流


GitLab 工作流是软件开发流程整个生命周期中可能采取的操作的逻辑序列。

GitLab 工作流会考虑我们在上一篇文章中探讨的 GitLab 流程。 具体如下:

  1. 想法:每个新提议都始于一个想法。
  2. 问题:探讨想法最有效的方法是为它创建问题。 您的团队和协作者可以在问题跟踪器中帮助您完善和改进问题。
  3. 计划:在讨论达成一致意见后,就可以开始编码了。 但首先,我们需要将问题指定至里程碑和问题看板,以此确定工作流的优先级并进行组织。
  4. 编码:现在,一切安排就绪后,我们就可以编写代码了。
  5. 提交:对草稿满意后,我们便可将代码提交到具有版本控制的功能分支。 上一篇文章详细介绍了 GitLab 流程。
  6. 测试:使用 GitLab CI 运行我们的脚本,以构建并测试应用程序。
  7. 审查:在脚本能够正常运行且测试和构建成功后,我们便可以让代码接受审查并获得批准。
  8. 暂存:现在应该将代码部署到暂存环境,以检查一切是否按预期进行,或者我们是否仍需要进行调整。
  9. 生产:如果一切顺利,便可将代码部署到生产环境!
  10. 反馈:现在可以回顾之前的流程,并检查有哪些阶段的工作需要改进。

再次说明,流程本身不是新的(或者 GitLab 独有的),并且可以通过其他工具来实现。

我们来讨论一下其中的几个阶段以及这些阶段涉及的内容。 还提供文档

问题和计划

GitLab 工作流的开始阶段以问题为中心,问题是指一个功能、一个错误或其他在语义上独立的工作。

问题有多个目的,例如:

  • 管理:问题具有截止日期、指定人员、用时和估计等, 可以帮助跟踪问题解决情况。
  • 行政管理:问题是里程碑的一部分,我们可以通过看板跟踪软件从一个版本过渡到另一个版本的进展。
  • 开发:问题具有与之相关的讨论和提交。

在计划阶段,我们可以按问题的优先级、里程碑、看板将问题分组,并获得问题的概览。

开发在前一部分进行了讨论,只需按照您希望使用的任何 git 流程执行操作即可。 我们开发了新功能并将其合并到 master 分支后,接下来应怎样操作?

持续交付

持续交付是一种软件工程方式,团队通过这种方式在短周期内制作软件,从而确保软件可以随时实现可靠发布。 它的目的是更快速、更频繁地构建、测试和发布软件。 这种方式允许对生产中的应用程序进行更多增量更新,从而帮助缩减交付更改的成本、缩短时间,以及降低风险。 简单且可重复的部署过程对于持续交付非常重要。

GitLab 中的持续交付

在 GitLab 中,持续交付配置按仓库以 YAML 配置文件形式定义。

  • 持续交付配置是一系列连续的阶段
  • 每个阶段都有一个或多个并行执行的脚本

脚本定义了一个操作以及执行该操作需要满足的条件:

  • 要执行的操作(运行 OS 命令、运行容器)?
  • 何时运行脚本:
    • 触发脚本的条件(特定分支)?
    • 之前的阶段失败时是否运行?
  • 手动运行还是自动运行?
  • 脚本在什么环境中运行?
  • 执行脚本后保存哪些工件(这些工件会从环境上传到 GitLab,以便轻松访问)?

环境是配置好的服务器或容器,可用于运行脚本。

运行程序用于在特定环境中执行脚本。 运行程序连接到 GitLab,并根据需要执行脚本。

运行程序可以部署在服务器上、容器上,甚至部署在本地机器上。

持续交付是如何实现的?

  1. 新提交推送到仓库中。
  2. GitLab 检查持续交付配置。
  3. 持续交付配置包含适用于所有情况的全部脚本,因此要过滤出应针对这一特定提交运行的一组脚本(例如提交到 master 分支仅会触发与 master 分支相关的操作)。 这组脚本称为管道
  4. 管道是在目标环境中执行的,执行结果会保存并显示在 GitLab 中。

例如,下面是提交到 master 分支后执行的一个管道:

管道包含四个阶段,各阶段连续执行

  1. 加载阶段会将代码加载到服务器中
  2. 测试阶段会运行单元测试
  3. 封装阶段包含两个并行运行的脚本:
    • 构建客户端
    • 导出服务器代码(主要用于提供信息)
  4. 部署阶段会将构建的客户端移动到 Web 服务器目录中。

我们可以看到,每个脚本都成功运行,如果其中一个脚本运行失败,则默认不会运行后面的脚本(但我们可以更改此行为):

如果我们打开脚本,可以查看日志并确定脚本运行失败的原因:

Running with gitlab-runner 10.4.0 (857480b6)
 on test runner (ab34a8c5)
Using Shell executor...
Running on gitlab-test...
Fetching changes...
Removing diff.xml
Removing full.xml
Removing index.html
Removing tests.html
HEAD is now at a5bf3e8 Merge branch '4-versiya-1-0' into 'master'
From http://gitlab.eduard.win/test/testProject
 * [new branch] 5-versiya-1-1 -> origin/5-versiya-1-1
 a5bf3e8..442a4db master -> origin/master
 d28295a..42a10aa preprod -> origin/preprod
 3ac4b21..7edf7f4 prod -> origin/prod
Checking out 442a4db1 as master...Skipping Git submodules setup$ csession ensemble "##class(isc.git.GitLab).loadDiff()"

[2018-03-06 13:58:19.188] Importing dir /home/gitlab-runner/builds/ab34a8c5/0/test/testProject/

[2018-03-06 13:58:19.188] Loading diff between a5bf3e8596d842c5cc3da7819409ed81e62c31e3 and 442a4db170aa58f2129e5889a4bb79261aa0cad0

[2018-03-06 13:58:19.192] Variable modified var=$lb("MyApp/Info.cls")

Load started on 03/06/2018 13:58:19 Loading file /home/gitlab-runner/builds/ab34a8c5/0/test/testProject/MyApp/Info.cls as udl Load finished successfully.

[2018-03-06 13:58:19.241] Variable items var="MyApp.Info.cls" var("MyApp.Info.cls")=""

Compilation started on 03/06/2018 13:58:19 with qualifiers 'cuk /checkuptodate=expandedonly' Compiling class MyApp.Info Compiling routine MyApp.Info.1 ERROR: MyApp.Info.cls(version+2) #1003: Expected space : '}' : Offset:14 [zversion+1^MyApp.Info.1] TEXT: quit, "1.0" } Detected 1 errors during compilation in 0.010s.

[2018-03-06 13:58:19.252] ERROR #5475: Error compiling routine: MyApp.Info.1. Errors: ERROR: MyApp.Info.cls(version+2) #1003: Expected space : '}' : Offset:14 [zversion+1^MyApp.Info.1] > ERROR #5030: An error occurred while compiling class 'MyApp.Info' ERROR: Job failed: exit status 1

编译错误导致脚本失败。

结论

  • GitLab 支持软件开发的所有主要阶段。
  • 持续交付可以帮助您自动执行软件构建、测试和部署任务。

后续内容

在下一篇文章中,我们将:

  • 安装 GitLab。
  • 将它连接到多个安装了 InterSystems 产品的环境。
  • 编写持续交付配置。

我们来探讨一下持续交付的运作方式。

首先,我们需要多个环境以及与之对应的分支。 代码进入此分支,并交付到目标环境:

环境分支交付有权提交的角色有权合并的角色
测试master自动开发者、所有者开发者、所有者
preprod预生产自动所有者
prod生产半自动(按下按钮进行交付)

所有者

作为示例,我们将使用 GitLab 流程开发一个新功能,并使用 GitLab CD 进行交付。

  1. 在功能分支中开发功能。
  2. 对功能分支进行审查并将其合并到 master 分支中。
  3. 一段时间(合并了多个功能)后,将 master 分支合并到 preprod 分支中
  4. 一段时间(用户测试等)后,将 preprod 分支合并到 prod 分支中

具体如下图所示:

  1. 开发和测试
    • 开发者将新功能的代码提交到单独的功能分支中
    • 功能稳定后,开发者将功能分支合并到 master 分支中
    • 来自 master 分支的代码被交付到测试环境,在其中进行加载和测试
  2. 交付到预生产环境
    • 开发者创建从 master 分支到 preprod 分支的合并请求
    • 仓库所有者在一段时间后批准合并请求
    • 来自 preprod 分支的代码被交付到预生产环境
  3. 交付到生产环境
    • 开发者创建从 preprod 分支到 prod 分支的合并请求
    • 仓库所有者在一段时间后批准合并请求
    • 仓库所有者按下“部署”按钮
    • 来自 prod 分支的代码被交付到生产环境

也可以用示意图形式表示此流程:

 

0
0 98
文章 Michael Lei · 九月 26, 2024 6m read

大家都搭建了测试环境。

有些人很幸运,可以在完全独立的环境中运行生产。

-- 佚名

.

在这一系列文章中,我想向大家介绍并探讨使用 InterSystems 技术和 GitLab 进行软件开发可以采用的几种方式。 我将介绍以下主题:

  • Git 101
  • Git 流程(开发流程)
  • GitLab 安装
  • GitLab 工作流
  • GitLab CI/CD
  • 包含容器的 CI/CD

第一部分将介绍现代软件开发的基础 – Git 版本控制系统和各种 Git 流程。

Git 101

虽然我们将主要探讨软件开发的概况以及 GitLab 如何帮助我们实现这一目标,但 Git,或者说 Git 设计中的几个基础的高级概念对于更好地理解后面的概念非常重要。

也就是说,Git 是基于这些概念的版本控制系统(还有更多概念,但这几个概念最为重要):

  • 非线性开发意味着,虽然我们的软件是从版本 1 到版本 2、再到版本 3 相继发布的,但实际上从版本 1 到版本 2 的升级是并行完成的 – 多名开发者会同时开发许多功能/错误修复。
  • 分布式开发意味着开发者独立于一个中央服务器或其他开发者,可以轻松地在自己的环境中进行开发。
  • 合并 – 基于前面提到的两个概念,我们会发现很多不同的版本同时存在,我们需要将它们统一成一个完整的状态。

我的意思不是说 Git 发明了这些概念。 Git 并没有发明这些概念, 而是使这些概念变得简单、流行,并加入了多个相关创新概念,也就是说,架构即代码/容器化改变了软件开发。

核心 git 术语

仓库是存储数据以及关于数据的元信息的项目。

  • “从物理层面来讲”,仓库是磁盘上的目录。
  • 仓库用于存储文件和目录。
  • 仓库还会存储每个文件的完整变更历史。

仓库可以:

  • 存储在您自己的计算机本地
  • 远程存储在远程服务器上

但从 git 的角度来看,本地仓库与远程仓库之间没有特殊的区别。

提交是仓库的固定状态。 很显然,如果每次提交都存储仓库的完整状态,我们的仓库很快就会变得非常大。 因此,提交会存储差异,也就是当前提交与其父提交之间的差异。

不同的提交可以具有不同数量的父提交:

  • 0 个 – 仓库中的第一个提交没有父提交。
  • 1 个 – 一切如常 - 我们的提交改变了仓库中的某些内容,就像在父提交期间一样
  • 2 个 – 当我们有两个不同的仓库状态时,我们可以将它们合并成一个新状态。 该状态和该提交就会有 2 个父提交。
  • >2 个 – 当我们将 2 个以上的不同仓库状态合并为一个新状态时,就会有 2 个以上的父提交。 这一概念与我们的讨论并没有特别大的关系,但它确实存在。

现在,对于父提交,每个与之不同的提交都被称为子提交。 每个父提交可以有任意数量的子提交。

分支是对提交的引用(或指针),如下图所示:

该图像显示的仓库具有两个提交(灰色圆圈),第二个圆圈是 master 分支的头部。 在我们添加更多提交后,仓库开始变成下图所示的状态:

这是最简单的情况。 我们的开发者一次负责处理一个更改。 但通常会有很多开发者同时负责处理不同的功能,我们需要使用提交树显示仓库中的变化。

提交树

我们从相同的起始状态开始。 仓库具有两个提交:

但现在,两名开发者在同时工作,为了避免相互干扰,他们在单独的分支中工作:

一段时间后,他们需要合并所做的更改,为此,他们创建了合并请求(也叫拉取请求), 顾名思义,该请求可将两个不同的仓库状态(本例中,我们要将 develop 分支合并到 master 分支中)合并为一个新状态。 接受相应审查并获得批准后,仓库状态如下图所示:

开发继续进行:

Git 101 - 总结

主要概念:

  • Git 是一个非线性的分布式版本控制系统。
  • 仓库用于存储数据以及关于数据的元信息。
  • 提交是仓库的固定状态。
  • 分支是对提交的引用。
  • 合并请求(也叫拉取请求)是将两个不同的仓库状态合并为一个新状态的请求。

如果您想了解更多关于 Git 的信息,可以阅读相关书籍

Git 流程

现在,读者已熟悉基本的 Git 术语和概念,我们来探讨一下如何使用 Git 管理软件生命周期的开发部分。很多实践(称为流程)介绍了使用 Git 的开发流程,但我们只会探讨其中两个:

  • GitHub 流程
  • GitLab 流程

GitHub 流程

GitHub 流程非常简单。 具体如下:

  1. 从仓库创建一个分支。
  2. 将更改提交到新分支
  3. 从您的分支发送一个拉取请求,其中包含您提议的更改,以发起讨论。
  4. 根据需要在您的分支上提交更多更改。 您的拉取请求将自动更新。
  5. 在分支准备好合并后,立即合并拉取请求。

我们需要遵守几条规则:

  • master 分支始终可部署(并且可正常运行!)
  • 不直接在 master 分支中进行开发
  • 在功能分支中进行开发
  • master 分支 == 生产* 环境**
  • 需要尽可能频繁地部署到生产环境

* 不要与“Ensemble 生产”混淆,这里的“生产”是指正式。

** 环境是配置好的代码运行位置,可以是服务器、虚拟机,甚至可以是容器。

如下图所示:

有关 GitHub 流程的更多信息,请参阅此处。 我们还提供了图解指南

GitHub 流程非常适合小型项目,如果您刚开始使用 Git 流程,可以尝试一下。 不过,GitHub 也会使用 GitHub 流程,因此也可以在大型项目中使用 GitHub 流程。

GitLab 流程

如果您还没有准备好立即部署到生产环境,GitLab 流程提供 GitHub 流程 + 环境。 具体做法是:在功能分支中进行开发(与上例相同),合并到 master 分支中(与上例相同),但这里有一个不同之处: master 分支仅等同于测试环境。 除此之外,还有链接到可能存在的各种其他环境的“环境分支”。

通常存在三个环境(可以根据需要创建更多环境):

  • 测试环境 == master 分支
  • 预生产环境 == preprod 分支
  • 生产环境 == prod 分支

进入其中一个环境分支的代码应立即移至相应的环境中,此流程可通过以下方式完成:

  • 自动(我们将在第 2 部分和第 3 部分探讨)
  • 半自动(与自动方式相同,唯一的区别是应按下按钮授权部署)
  • 手动

完整的流程是:

  1. 在功能分支中开发功能。
  2. 对功能分支进行审查并将其合并到 master 分支中。
  3. 一段时间(合并了多个功能)后,将 master 分支合并到 preprod 分支中
  4. 一段时间(用户测试等)后,将 preprod 分支合并到 prod 分支中
  5. 在我们进行合并和测试时,多个新功能已开发完毕并合并到 master 分支中,因此转到  3。

具体如下图所示:

有关 GitLab 流程的更多信息,请参阅此处

结论

  • Git是一个非线性的分布式版本控制系统。
  • Git 流程可用作软件开发周期的准则,有多种 Git 流程可供选择。

链接

讨论问题

  • 您使用 Git 流程吗? 使用哪一种?
  • 您为普通项目使用多少个环境?

后续内容

在接下来的部分中,我们将:

  • 安装 GitLab。
  • 探讨一些建议的调整。
  • 讨论 GitLab 工作流(不要与 GitLab 流程混淆)。

敬请关注。

0
0 129
文章 Michael Lei · 八月 17, 2024 3m read

各位社区成员,大家好,

利用面向您的组织中的各个角色提供的全套 InterSystems 学习资源(在线或面授形式),您可以全面挖掘 InterSystems IRIS 的潜力,并帮助您的团队完成入门流程。 开发者、系统管理员、数据分析师和集成商可以快速上手。

学习服务提供的资源

在深入学习角色特定的资源之前,我们先来总体了解一下现有的学习资源:

  • 💻 在线学习:在 learning.intersystems.com 上免费注册,以访问自定进度的课程、视频和练习。 您还可以完成基于任务的学习路径或基于角色的计划,以促进您的职业发展。
  • 👩‍🏫 课堂培训:查看直播、面授或虚拟课堂培训的时间安排,或为您的团队申请不公开课程。 访问 classroom.intersystems.com 了解详细信息。
  • 📘 InterSystems IRIS 文档:全面的参考资料、指南和操作说明文章。 探索文档
  • 💬 开发者社区:与其他开发者互动、发布问题、阅读文章并及时了解最新公告。 请先阅读本帖,其中介绍了在开发者社区中学习的技巧
  • 📧 支持:如需获取技术支持,请发送电子邮件至 support@intersystems.com

针对各个角色提供的入门资源

开发者

系统管理员

数据分析师

集成商

项目经理

通过这些学习资源,您的团队将掌握相应知识,从而最大限度地利用 InterSystems IRIS 的功能,推动组织的发展并取得成功。 如需获取其他帮助,请随时在此发布问题或咨询您的专属销售工程师。

认证机会

certification badge 在您和您的团队成员接受足够时长的培训并获得相应经验后,你们可以申请认证来证明在 InterSystems 技术方面具备相应的技能和专业知识:

0
0 472
文章 Jeff Liu · 六月 30, 2024 7m read
Purpose of this article

有两篇很棒的有关删除消息关联的孤儿记录的内容以及如何处理孤儿的问题的WRC议最佳实践文章Ensemble Orphaned Messages | InterSystems Developer Community | Best DeleteHelper - A Class to Help with Deleting Referenced Persistent Classes (intersystems.com)
本文并不是要取代 Intersystems 专业人员撰写的这些文章,而是要在此基础上介绍我们如何利用这些信息和其他讨论(包括我们实际清理这些数据的方法)来帮助我们的数据库变得更加紧凑。

情况说明:

我们的备份越来越多。年初的时候,我们遇到过一台服务器被强制故障的情况,需要进行还原。由于数据库庞大,即使复制这个数据库也需要很长时间,更不用说还原重建shadow服务器了。因此,我们不得不决定最终解决这一增长问题。最初的原因已经确定 

  1. 开箱即用的任务或者在某些时候假定已运行,但没有勾选信息体。这是因为在查询其中一个消息体时,我们得到了来自 10 多年前的 ID 1。该任务是最佳实践中提到的默认 Ens.Util.Tasks.Purge。这就引出了流程中的提示 1 

理解你的数据

0
0 176
文章 Hao Ma · 五月 17, 2024 3m read

最近有某国内三甲医院为满足评级和飞行检查要求,希望提升HIS和IRIS的SQL查询效率,客户和实施工程师整理了一个慢查询的SQL列表, 有一些查询比较慢, 查询时间在甚至大于60分钟。

在我们和厂商共同努力下,对整个库的SQL查询做了优化。 下表是记录了我们在进行了大部分优化工作后的结果,您可以看到大多查询从几十分钟减少到了几十秒甚至1秒以内。其中有几个慢到几分钟的查询,最后经过细调, 也把查询耗时减少到了一分钟以内。 优化的效果还是很明显的。

这里我分享一下操作的要点,以便给其他有同样问题的客户一个思路。

其实如果您看过我前面的帖子,应该已经有了基本的概念。我就把工作流程总结一下,其实就这么几个步骤:

步骤一:

检查硬件配置。 配置中和SQL性能相关的有这么几个: 1. 数据缓存大小,应该至少为物理内存的一半以上。 2. BBSIZE, 也就是单个进程最大的内存占用,对应不同的Caché/IRIS版本和不同的应用,这个配置有区别,但当然是越大越好,询问您的实施工程师配置是否正确。 3. 是否使用了大页内存,这个能从messages.log里看到。

步骤二

执行Tunetable。 在上面说的这个客户的系统上从来没人执行过Tunetable, 因此SQL引擎其实是没法正确工作的。执行后基本可以解决80%的慢SQL问题。时间短风险小见效快, 找个半夜业务小的时候直接在生产环境执行。

执行完之后,只剩下20-30个SQL还是太慢(超过5秒), 之后的工作我们集中在这些Case上,

步骤三

校验索引。 在生产环境上数据和索引出错非常普遍,因为有人/业务代码直接去改Global. 有的是没改对, 有的是改的过程出了问题,比如有进程没做好错误管理,出问题了没有回滚等等。SQL表数据的完整性出问题,一个结果是查的数不对, 这是显见的,还有一个是查的慢, 这个大部分人想不到。

校验索引是发现这个问题的最有效的办法。 原则上说, 所有的索引都应该执行一下,但因为时间长,影响业务,我们的做法是把相关用到的索引校验了一遍。其中发现了很多数据被修改的问题,比如必须的字段里面是空的, 要求是数字的字段里面放的是字符串等等等等。

校验索引比重新build索引要慢的多, 但对业务的影响也小的多。

步骤四

使用bitmap和bitmap extent索引。本来bitmap extent是不用人工添加的。创建任何一个bitmap索引,系统会自动添加bitmap extent。然而客户用的是SQLStorage的存储格式,修改会非常麻烦。但结果是值得的,上面所处理的绝大多数SQL, 查询时间都降到了60秒以下, 和count()相关的查询, 更是可以从1000秒直接减少到5秒以内。

步骤五

对于极少数查询时间已经提高了很多,但还是不很如人意的SQL, 我们仔细的检查查询计划,用查询关键字来做最后的优化。在好几个查询里, %PARALLEL证明是起作用的, 也就是说,本来用并行多进程查询是可以提高效率的, 但SQL引擎没自动判断出来。

除此之外, 修改SQL语句有时候是可以改善查询速度的,尤其是含子查询, IN, TOP,ORDER BY的语句, 通过检查查询计划,比较不同查询计划的执行情况,可以做出一下成功的性能改善。

欢迎讨论指正,也欢迎感兴趣的客户前来咨询我们gcdpsales@intersystems.com获取更多信息。

0
0 339
文章 Hao Ma · 五月 15, 2024 4m read

SQL查询优化器一般情况下能给出最好的查询计划,但不是所有情况都这样,所以InterSystems SQL还提供了一个方式, 也就是在查询语句里加入optimize-option keyword(优化关键字), 用来人工的修改查询计划。

比如下面的查询:

SELECT AVG(SaleAmt) FROM %PARALLEL User.AllSales GROUP BY Region

其中的%PARALLEL, 就是最常用的优化关键字, 它强制SQL优化器使用多进程并行处理这个SQL。

您可以这样理解: 如果查询优化器足够聪明,那么绝大多数情况下,根本就不需要优化关键字来人工干预。因此,您也一定不奇怪在不同的IRIS/Caché版本中, 关键字的表现可能不一样。越新的版本,应该是越少用到。比如上面的%PARALLEL, 在Caché的大多数版本中, 在查询中加上它一般都能提高查询速度,而在IRIS中,尤其是2023版本以后, 同样的SQL查询语句,很大的可能查询优化器已经自动使用多进程并行查询了,不再需要用户人工干预了。

因此,先总结有关优化关键字的要点:

  1. 优化关键字主要是FROM语句中使用。 UPDATE, INSERT语句也有可以使用的关键字,比如%NOJOURAL等等, 这里我不介绍了,请各位自己查询文档。

    INSERT, UPDATE的关键字常用的有:%NOCHECK %NOINDEX %NOLOCK %NOTRIGGER 等等

  2. 各个不同版本的文档中这部分内容有少许的不同。

  3. 使用查询关键字要结合阅读查询计划,需要经验的积累。用的多了, 在当前版本什么样的查询需要添加关键字就比较有数了。

最新版本的联机文档在: Specify Optimization Hints in Queries | Configure SQL Performance Options

%PARALLEL

指定查询使用多个进程并行处理。在Query Plan中您可以得到证实。有关Query Plan的阅读请看前面的帖子。

%IGNOREINDEX

指定不用某一个或者某几个index。比如以下查询:

select min(ps_supplycost) 
                from %PARALLEL
                %IGNOREINDEX SQLUser.supplier.SUPPLIER_PK
                %IGNOREINDEX SQLUser.part.PART_PK
                %IGNOREINDEX SQLUser.nation.Nation_PK 
                %IGNOREINDEX SQLUser.region.REGION_PK
                        partsupp,
                        supplier,
                        nation,
                        region
                where p_partkey = ps_partkey
                        and s_suppkey = ps_suppkey
                        and s_nationkey = n_nationkey
                        and n_regionkey = r_regionkey
                        and r_name = 'AFRICA'
                        ...

为什么要强制不用某些索引?

一个是用在测试中,经常会比较不同索引的表现。比如你原来有个复合索引,它希望试试新创建的索引是不是更好, 那么很可能您需要告诉SQL引擎不要用以前的索引了。

还有就是您发现某个索引的使用没有让查询性能变好,强制不用它结果可以使用另一个索引,从而来得到更好的查询速度。

%ALLINDEX

用于测试所有可用的索引。

SQL引擎默认会在多个可用的索引中选中它判断最高效的,但这个判断不是总正确。加入%ALLINDEX会在生成查询计划前,测试所有可用的索引,以证实或者调整判断。 用到比较多的情况是有多个范围查询字句的情况。在Caché和早期IRIS版本中, 很多情况下, 使用%ALLINDEX会带来性能的提升, 尽管对所有可用索引做测试会有个额外开支.

比如以下的语句,

SELECT TOP 5 ID, Name, Age, SSN FROM %ALLINDEX Sample.Person WHERE 
(:Name IS NULL or Name %STARTSWITH :Name)
AND
(:Age IS NULL or Age >= :Age)
}

%NOINDEX

在最新版的IRIS文档中, 这个关键字已经去掉了。 我自己的测试中,在2022年后的IRIS中, 它其实已经不起作用了。 但在Caché中, 非常多的使用%NOINDEX的例子。

Caché在线文档中的这段是这么说的:当绝大多数数据被条件选中(或未被选中)时,这种方法最常用。在小于 (<) 或大于 (>) 条件语句下,使用 %NOINDEX 条件级提示通常是有益的。对于“等于”条件语句,使用 %NOINDEX 条件级提示没有任何好处。对于连接条件语句,不支持在 =* 和 *= WHERE 子句外部连接中使用 %NOINDEX;而在 ON 子句连接中使用 %NOINDEX。

这是文档上的例子: E.Age<65已经包含了绝大多数的表记录,那么使用相应的索引可能不经济,因为后面取“Name"还是要直接回表操作,这样的情况, 不用E表的Age的索引,查起来还快一些。

SELECT P.Name,P.Age,E.Name,E.Age
FROM %ALLINDEX Sample.Person AS P LEFT OUTER JOIN Sample.Employee AS E
     ON P.Name=E.Name
WHERE P.Age > 21 AND %NOINDEX E.Age < 65

幸好新版IRIS变的智能了。

%FIRSTTABLE, %STARTTABLE

这两个关键字都是强制查询计划中对JOIN的执行从那个表开始。如果SQL引擎没法给出正确的判断的话,人工指定是需要的。

其他的关键字包括: %FULL, %INORDER, %NOFLATTEN, %NOMERGE, %NOREDUCE, %NOSVSO, %NOTOPOPT, %NOUNIONOROPT, 等等。 不同的版本会有出入。如果您需要了解更多的关键字的使用,可以到community.intersystems.com里搜索相关的文章,比如这篇Force inner select to be executed, Query Plan Error or Correct Estimation

0
0 138
文章 Hao Ma · 四月 12, 2024 3m read

SQL性能监控是DBA最重要的日常工作。经常被问起:"Caché/IRIS怎么发现慢SQL"? 答案很简单: 到管理门户的SQL页面,点开如下的“SQL语句“子页, 您能看到这个命名空间的所有执行过的SQL语句,知道每个SQL语句执行了多少次,平均执行时间是多少, 被那个客户端编译的,第一次执行是那一天等等。

请看下面的截图

图中的各个栏目基本都不需要解释,有个别的内容在这里总结一些:

  • 表/视图/存储过程名称:列出这个查询使用的所有的表/视图/存储过程的名字。如果你想看某个表有关的查询,可以使用上面的过滤器

  • 位置(Location) : 对于动态查询, 列出所使用的缓存的查询的类名,对于嵌入SQL(Embedded SQL)查询,列出使用的routine名字。

  • 每个字段的标题栏可以用于排序,比如上图是按执行次数倒序显示的,所以前几位都是执行了很多的INSERT。 如果是日常维护查找慢SQL, 您可以按平均时间倒序显示。

  • 计划状态: 通常是"Unfrozn"或者“Unfrozen/Parallel"。除非您需要升级或者有“Frozen Qeury Plan“的需要,您可以不关心这个栏目。

  • 用鼠标单击上图的最左列或者最右列“SQL声明文本”, 会显示这个SQL语句的详细执行数据。 注意这个页面上的两个按钮: “导出” 和**”查询测试“**, 您可以试试它们。

关于如何阅读“SQL Statement”, 上面说了个大概,更多的细节请阅读在线文档Analyze SQL Statements and Statistics

最后几个要点:

  • SQL Statement可以导入导出

  • 统计采集的工作一个小时执行一次,所有SQL Statement页面不一定能显示最近一个小时内的操作统计。

  • 如果你要清理“SQL Statement"统计,或者要重新计数,或者要去掉已经"STALE"的查询统计。(如果您删除了一个表,它的记录不会从SQL Statement统计里除去), 请参考这部分操作:Stale SQL Statments

  • 使用SQL查询“SQL Statement"

    如果您需要对SQL Statment做分析,或者设置告警或者通知,您需要学习这部分内容: Querying SQL Statements, 简单说,你需要查询这几个表:INFORMATION_SCHEMA.STATEMENTSINFORMATION_SCHEMA.STATEMENT_LOCATIONSINFORMATION_SCHEMA.STATEMENT_RELATIONSINFORMATION_SCHEMA.CURRENT_STATEMENTS

注意: 如果您在在线文档中看到“SQL Performance Analysis Toolkit的内容,它说的和上面的"SQL Statement"不是一回事,千万别搞混了。"SQL Performance Analysis Toolkit"对大部分维护人员非常不常用,我会在后面介绍。

另一个可以带来混淆的术语叫"SQL Runtime Statistics". IRIS的在线文档SQL Runtime Statistics章节说它是SQL Statment的执行步骤,而且*“The gathering of SQL runtime statistics is always on and cannot be turned off.”*。而在维护页面的"System Explorer>Tools>SQL Performance Tools>SQL Runtime Statistics"里,它其实是另一个意思。我认为都是历史原因造成的。

2
0 190
文章 Hao Ma · 四月 16, 2024 3m read

索引分析器工具用来分析索引的使用情况,对DBA和开发者非常有用。 他们需要知道那些查询进行了全表扫描,那些查询缺失了索引, 而那些索引从来又从来没有被用过。多余的索引降低系统性能,浪费了磁盘空间。

索引使用情况

到“管理门户”的" 系统 > SQL 性能工具 > SQL 索引分析器", 点击**“索引使用情况”**, 您将看到这样的图

执行SQL语句查询会带来更多的灵活性。上面的查询可以写成下面这个SQL,

SELECT TableName, indexname, UsageCount
FROM %SYS_PTools.UtilSQLAnalysisDB order by usagecount desc

2016年以后的Caché版本就已经有了'索引使用情况'的查询。使用管理门户没有区别, 但SQL语句不同,使用的是比较老的类和表名,各位请参考文档。

注意上图中另外几个按钮,它们的介绍在文档的这个链接, 简单的做个翻译:

全表扫描的查询:

可识别当前命名空间中进行全表扫描的所有查询。应尽可能避免全表扫描。全表扫描并非总能避免,但如果某个表有大量全表扫描,则应检查为该表定义的索引。通常情况下,表扫描列表和临时索引列表会重叠;修复一个会移除另一个。结果集列出了从最大块计数到最小块计数的表。显示计划链接可显示语句文本和查询计划。

使用临时索引的查询

该选项可识别当前命名空间中所有建立临时索引以解析 SQL 的查询。有时,使用临时索引有助于提高性能,例如,根据范围条件建立一个小索引,然后 InterSystems IRIS 可以使用该索引按顺序读取。有时,临时索引只是不同索引的子集,可能非常高效。其他时候,临时索引会降低性能,例如,扫描主MAP以在有条件的属性上建立临时索引。这种情况表明缺少一个所需的索引;你应该在类中添加一个与临时索引匹配的索引。结果集列出了从最大块计数到最小块计数的表。显示计划链接可显示语句文本和查询计划。

缺少JOIN索引的查询

该选项会检查当前命名空间中所有使用JOIN的查询,并确定是否定义了支持该JOIN的索引。它将可用来支持JOIN的索引从 0(无索引)排到 4(索引完全支持JOIN)。外关联需要单向索引, INNER JOIN需要两个方向的索引。默认情况下,结果集中只包含 JoinIndexFlag < 4 的记录。 JoinIndexFlag=4 表示有一个完全支持JOIN的索引。

具有离群值Outlier索引的查询

该选项可识别当前命名空间中所有具有异常值的查询,并确定是否定义了支持异常值的索引。它将可用来支持异常值的索引从 0(无索引)到 4(索引完全支持异常值)进行排序。默认情况下,结果集中只包含 OutlierIndexFlag < 4 的记录。 OutlierIndexFlag=4 表示有一个完全支持异常值的索引。

0
0 178
文章 Hao Ma · 四月 10, 2024 7m read

为什么要读Query Plan, 在线文档中有句话是这么说的:

While the SQL compiler tries to make the most efficient use of data as specified by the query, sometimes the author of the query knows more about some aspect of the stored data than is evident to the compiler. In this case, the author can make use of the query plan to modify the original query to provide more information or more guidance to the query compiler.

翻译一下是这样:系统给你的查询计划并不总是最好的,如果您能对查询计划,可以人工做更精细的优化。

我们先看看读Query Plan的几个基本知识:

MAP

An SQL table is stored as a set of maps. 您有看到3种map: Master map, index map, bitmap.

# 回表读主数据,
- Read master map DWBC.CT_Dept.IDKEY, using the given idkey value.

# 读普通索引
Read index map DWBC.CT_MDRDictionary(T1).UniCodeIdx, using the given %SQLUPPER(UniCode), and getting T1.ID.

# 读bitmap索引
Read bitmap index My.ppl1.idxWLRecDep, looping on %SQLUPPER(WLRecDep) (with a given set of values) and bitmap chunks.

temp-file

在复杂查询时,中间过程会存在“temp-file"里。如果您的内存设置合理,通常这个"temp-file"只存在于内存,不会有IO操作。

和map一样,temp-file也是有subscription(下标),也可以有node, 您可以认为它和普通的索引是一样的global记录,通常您可以把temp-file当成一个临时的索引,只是它在内存里。

Divide and process in parallel

一个查询可以被多个进程并行处理。一种情况是用idkey分开,每一段用一个进程处理,看一个例子

• Divide extent bitmap My.column(FACTTT).%%DDLBEIndex into subranges of bitmap chunks.
• Call module A in parallel on each subrange, piping results into temp-file C.

基础教学完成。现在我们来一起看看一个真实的Query Plan。最简单的查看Query plan的方式是在IRIS管理门户的SQL页面,如果您习惯用SQL客户端, 也可以执行“EXPLAIN ..."得到查询计划。

以下的这个查询是一个主表和一个字典表的关联查询,得到一个时间段的结果,按照字典表中的科室代码分组。

主计划部分

# SQL compiler会在查询语句上附加信息,放在 /*#OPTIONS*/块里。比如下面的“DynamicSQLTypeList”说的是内部SQL查询的类型,
# RTPC指的是Runtime Plan Choice,是一个优化的特性,这些普通的SQL用户可以先不用了解。
# 如果非要知道什么意思,可以查看链接:https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=GSOC_rtpc
# 这里使用了RTPC的原因是fact.WLPatDep字段有Outlier值

Statement Text
SELECT dwbc . CT_Dept . CTD_Code , dwbc . CT_Dept . CTD_Desc , SUM ( WLTotalFee ) 
FROM my . ppl1 AS fact LEFT JOIN dwbc . CT_Dept ON fact . WLPatDep = dwbc . CT_Dept . CTD_Code 
WHERE fact . WLOrdDate BETWEEN ? AND ? 
GROUP BY dwbc . CT_Dept . CTD_Code 
/*#OPTIONS {"DynamicSQLTypeList":"1,1"} */
/*#OPTIONS {"rtpc-utility":1} */
/*#OPTIONS {"rtpc-truth-value":["heCFqw8mm2^1"],"rtpc-range":["2^1","3^.00001"]} */


# Query Plan

• This query plan was selected based on the runtime parameter values that led to:
    Improved selectivity estimation of a <= condition on WLOrdDate and a >= condition on WLOrdDate.
    Boolean truth value of a NOT NULL condition on arg1.

# 除非您比较多个不同的查询计划,这个相对花费的值没有意义
Relative Cost = 127308


#调用Module C, 它会创建一个temp-file B
• Call module C, which populates temp-file B.
# temp-file B的每一行对应一个CTD_Code,也就是科室代码, 因此,temp-file B也就是最后的结果集。
• Read temp-file B, looping on %SQLUPPER(CTD_Code).
• For each row:
    - Output the row.

说明: Module C 是主处理模块,它创建一个临时文件temp-file B, 其中每一个记录对应一个科室表中的科室。

Moduel C

# 调用Module B,产生temp-file A, 
Call module B, which populates bitmap temp-file A.
# 对temp-file A的每一行,也就是查询范围的每一天,得到这个时段内的所有主表ID,并且“looping on"
• Read bitmap temp-file A, looping on FACT.ID.
# 对应上面的"looping on", 因此每一行是一个FACT.ID
• For each row:
		# 回表,得到这行的数据
    - Read master map My.ppl1(FACT).IDKEY, using the given idkey value.
    # 使用CTD_Code的值去查字典表,这里没有清楚的写明主表和字典表的关联
    - Read index map DWBC.CT_Dept.UqCTDCodeIdx, using the given %SQLUPPER(CTD_Code), and getting ID.
    # 得到字典表中的这行数据
    - Read master map DWBC.CT_Dept.IDKEY, using the given idkey value.
    # 确认这行记录里的CTD_Code不是NULL
    - Test the NOT NULL condition on %SQLUPPER(CTD_Code).
    # 如果字典表中没有任何一行数据匹配 ON 的条件,将会额外生成一行所有列为NULL的数据
    - Generate a row padded with NULL for table DWBC.CT_Dept if no row qualified.
    # 查看temp-file B的文件里有没有这个科室的值
    - Check distinct values for %SQLUPPER(CTD_Code) using temp-file B,
        subscripted by %SQLUPPER(CTD_Code).
    # 这里的distinct指的是科室代码, 创建的temp-file B的存储
    # 	^tempB(1) = ("心内科",10块人民币)
		#		^tempB(2) = ("心外科",50块人民币)
		#	  ...
    - For each distinct row:
        · Add a row to temp-file B, subscripted by %SQLUPPER(CTD_Code),
            with node data of CTD_Desc and FACT.WLTotalFee.
    # 把temp-file B汇总,最后的结果集
    - Update the accumulated sum(FACT.WLTotalFee) in temp-file B,
        subscripted by %SQLUPPER(CTD_Code)

Module B

# 读标准索引idxWLOrdDate, 它的格式是^My.ppl1I("idxWLOrdDate",日期下标,表ID)	=	""
• Read index map My.ppl1(FACT).idxWLOrdDate, looping on FACT.WLOrdDate (with a range condition) and FACT.ID.
# 生成一个查询范围内的OrderDate的bitmap索引,被存在一个临时文件temp-file A
• For each row:
    - Add FACT.ID bit to bitmap temp-file A.

总结

好了, 当看过一个执行计划后,您就基本可以使用执行计划来发现SQL性能的问题了。比如上面的这个计划,我们可能有两个想法:

  1. 既然Moudle B是生成了一个OrdDate的bitmap索引,那么我干脆创建一个OrdDate的bitmap索引不好吗?

答案是不好, 详细请看前面关于bitmap索引的文章

  1. 为什么没有用多进程处理?有没有办法强迫使用多进程,会更快吗?

在查询语句里加入*%PARALLE*, 可以强迫使用多进程。

*如果您有兴趣,可以看看多进程的查询计划,当做个练习,:) *

Statement Text
SELECT dwbc . CT_Dept . CTD_Code , dwbc . CT_Dept . CTD_Desc , SUM ( WLTotalFee ) 
FROM %PARALLEL my . ppl1 AS fact LEFT JOIN dwbc . CT_Dept ON fact . WLPatDep = dwbc . CT_Dept . CTD_Code WHERE fact . WLOrdDate BETWEEN ? AND ? GROUP BY dwbc . CT_Dept . CTD_Code /*#OPTIONS {"DynamicSQLTypeList":"1,1"} */ /*#OPTIONS {"rtpc-utility":1} */ /*#OPTIONS {"rtpc-truth-value":["heCFqw8mm2^1"],"rtpc-range":["2^1","3^.00001"]} */
Query Plan

• This query plan was selected based on the runtime parameter values that led to:
    Improved selectivity estimation of a <= condition on WLOrdDate and a >= condition on WLOrdDate.
    Boolean truth value of a NOT NULL condition on arg1.
Relative Cost = 127308

• Call module J, which populates temp-file C.
• Read temp-file C, looping on %SQLUPPER(CTD_Code).
• For each row:
    - Output the row.
Module: J

• Divide index map My.ppl1(FACT).idxWLOrdDate into subranges of subscript values.
• Call module A in parallel on each subrange, piping results into temp-file D.
• Read temp-file D, looping on a counter.
• For each row:
    - Check distinct values for %SQLUPPER(CTD_Code) using temp-file C,
        subscripted by %SQLUPPER(CTD_Code).
    - For each distinct row:
        · Add a row to temp-file C, subscripted by %SQLUPPER(CTD_Code),
            with node data of CTD_Desc.
    - Update the accumulated sum([value]) in temp-file C,
        subscripted by %SQLUPPER(CTD_Code)
Module: A

• Call module C, which populates temp-file B.
• Read temp-file B, looping on %SQLUPPER(CTD_Code).
• For each row:
    - Add a row to temp-file D, subscripted by a counter, with node data of %SQLUPPER(CTD_Code), CTD_Desc, and sum([value]).
Module: C

• Call module B, which populates bitmap temp-file A.
• Read bitmap temp-file A, looping on FACT.ID.
• For each row:
    - Read master map My.ppl1(FACT).IDKEY, using the given idkey value.
    - Read index map DWBC.CT_Dept.UqCTDCodeIdx, using the given %SQLUPPER(CTD_Code), and getting ID.
    - Read master map DWBC.CT_Dept.IDKEY, using the given idkey value.
    - Test the NOT NULL condition on %SQLUPPER(CTD_Code).
    - Generate a row padded with NULL for table DWBC.CT_Dept if no row qualified.
    - Check distinct values for %SQLUPPER(CTD_Code) using temp-file B,
        subscripted by %SQLUPPER(CTD_Code).
    - For each distinct row:
        · Add a row to temp-file B, subscripted by %SQLUPPER(CTD_Code),
            with node data of CTD_Desc and FACT.WLTotalFee.
    - Update the accumulated sum([value]) in temp-file B,
        subscripted by %SQLUPPER(CTD_Code)
Module: B

• Read index map My.ppl1(FACT).idxWLOrdDate, looping on the subrange of FACT.WLOrdDate and FACT.ID.
• For each row:
    - Add FACT.ID bit to bitmap temp-file A.

0
0 139
文章 Hao Ma · 三月 22, 2024 4m read

这个帖子内容有点深。如果您读的有困难,请直接跳过这篇,对绝大多数IRIS/Caché使用者,它一点都不重要。

数据库表的Collation(排序规则)本来是一个非常简单的概念。说到它是因为曾经发现过由Collation引起的性能问题。

我试图用一句话来解释数据库的排序规则:

  • 绝大多数数据库因为业务查询需要,保存的字符型数据是不分大小写的。当你执行一个 order by, group by, distinct,like等等条件查询时,因为这个不分大小写的collation,你得到的结果也不分大小写。例如,对名字做group by, James, james一定是在一组。
  • 如果非要区分大小写,会在查询的时候使用一个函数
  • 因为要操作非英语的字符集,以及可以被当作字符看待的数字类型,适应不同的排序规则,一个数据库可能有很多种Collation类型。

很简单,在表一级定义Collation的SQL语句是:

CREATE TABLE Sample.MyNames (
    LastName CHAR(30),
    FirstName CHAR(30) COLLATE SQLstring)

IRIS/Caché的Collation

事情在IRIS/Caché里变的有点复杂。

  1. 对于一个字段,可以分别在字段上和索引上定义Collation。 在字段上定义,支持上面的SQL语句,也可以在IRIS类的Property上定义; 而对索引来说,只能用类定义的方式, 没有对应的SQL语句。
  2. 为了应对多种不同的字符集,再加上IRIS/Caché发展的历史上的一些遗留,Collation的类型可以有很多种。而今天绝大多数情况下使用的就只有两种:EXACT: 区分大小写;SQLUPPER : 不区分大小写。这里我也是只说这两种。

让我们还是从Patient表开始。 这是它的字段

image-20240321175123299

这是它的索引

image-20240321175211437

这是系统默认的状态,我并没有在字段或者索引上做任何设置。这里我抛出第一个规则:

规则1: 默认的字段排序规则是SQLUPPER。在字段上创建索引,默认使用字段的排序规则

这非常好记,业务部排序不分大小写很合适。索引,比如上面的'idxName'有一栏叫列,您可以理解成global的下标。它使用了一个function, $$$SQLUPPER(), 确保所有的下标都是大写。得到的结果像这样:

^User.PatientI("idxName"," ADAM",47)	=	""
^User.PatientI("idxName"," AHMED,BRENDAN S.",57)	=	""
^User.PatientI("idxName"," ANDERSON,JAMES Q.",59)	=	""
^User.PatientI("idxName"," CLINTON,MARY L.",51)	=	""

接着我们说第2个规则:

规则2: 如果字段和索引上的Collation类型不一样,那么有两种情况

  • 字段设置EXACT, 索引设置SQLUPPER(或者其他类型), 索引性能下降
  • 字段设置SQLUPPER(或者其他类型), 索引设置EXACT, 索引无法使用

然后问题来了,根据规则一,既然系统默认的表现是最好的, 我干嘛要故意把两者的排序类型改成不一样呢?

答案是:最大的可能不是故意的,而是不小心弄错了,基本都是和SQLStorage有关。

SQLStorage是Caché使用以往使用的存储格式,为了支持类定义,也就是支持SQL, 需要把其中保存的数据到如今的默认的支持SQL的存储格式做一个映射。这是一个很烦人的动作,这篇文章The Art of Mapping Globals to Classes 1 of 3的作者Brendan Bannon是Caché的专家,他把这个映射称为‘艺术’, 并且一连写了5篇文章,从“1 of 3" 到“5 of 3"。

在使用SQLStorage里表里,索引是定义在一个<SQLMAP>的XML节点。我们找个例子看看:

这是SQLUser.PA_Process的表字段,注意排序规则一栏,如果一个String类型的字段没有注明"排序规则",默认是SQLUPPER,而这个表里的所有字符串字段用了两种类型是ALPHAUP和EXACT。 为什么不用默认的SQLUPPER, 我认为是为了向前兼容早期的代码。

image

然后我们看看索引

image-20240322125921326

注意下面索引定义的的列,也就是下标取值,也就是索引定义的Collation

  • IndexCode: ALPHAUP(SQLUser.PAC_Ward.WARD_Code)
  • indeDesc: $$ALPHAUP({SQLUser.PAC_Ward.WARD_Desc})
  • IndexLoc: 整数列,没有collation

我们已经看出来了字段和索引对应,他们应该是一样的。然而,这个对应是人工配置的,索引在代码里的定义我贴在下面。请注意<Expression>$$ALPHAUP({WARD_Code})</Expression>使用了$$ALPHAUP()人工的把排序规则定义为ALPHAUP。 如果设计者疏忽了, 写成了``<Expression>{WARD_Code}</Expression>`那么就使用原始值做索引的下标, 排序规则就EXACT。

如果您回去看看上面的规则2, 你会发现这个索引就掉到了一个坑里:

  • 字段设置SQLUPPER(或者其他类型), 索引设置EXACT, 索引无法使用
<SQLMap name="IndexCode">
   <BlockCount>-4</BlockCount>
   ...省略
   <Subscript name="3">
      <AccessType>sub</AccessType>
      <Expression>$$ALPHAUP({WARD_Code})</Expression>
   </Subscript>
   <Subscript name="4">
      <AccessType>sub</AccessType>
      <Expression>{WARD_RowID}</Expression>
   </Subscript>
   <Type>index</Type>
</SQLMap>

怎么发现没有正常使用或者性能太差? 阅读查询计划或者查看索引使用统计。我会在后面的帖子介绍。

0
0 162
文章 Hao Ma · 三月 21, 2024 1m read

Bitmap索引是指对某个,或者某几个字段建立的bit map(位图映射)。如果是对整个表的记录,也就是表的%ID做位图映射,得到的特殊的bitmap索引在IRIS/Caché里被称为Bitmap Extent。

建立Bitmap Extent索引的目的就是加快COUNT(*)的执行。提高了多少呢? 下面两个显示的是最简单的全表查询花费的时间:

  • 不使用Bitmap Extent : 1.3810s
  • 使用Bitmap Extent: 0.0038

相差有几百倍。

有关Bitmap Extent你需要了解:

  • IRIS中不需要人工创建。当在表中创建了任何一个Bitmap索引, 系统会为这个表自动添加一个Bitmap Extent, 名字是“$类名”, 比如上图中的$ppl1。
  • Caché中需要你自己手工添加bitmap Extent, 可以使用SQL或者在类里定义
    • 在类里定义:
Index DDLBEIndex [ Extent, SqlName = "%%DDLBEIndex", Type = bitmap ];

 

  • SQL定义
CREATE BITMAPEXTENT INDEX Patient ON TABLE Sample.Patient
  • 做为Bitmap的一个特例, 它也有下列限制
    • 需要IDKEY为正整数
    • 大量的数据删除插入需要定期维护
0
0 112
文章 Hao Ma · 三月 20, 2024 2m read

**复合索引(combined index)**也被称为组合索引或者联合索引,顾名思义,就是一个索引建立在多个字段上。当用这些字段为条件查询时,相比对每个字段单独做索引,复合索引能给出很好的性能,还能减少索引的数量。

为什么能减少索引的数量? 通常来说,也就是在其他数据库,联合索引符合”最左匹配“的原则。在BING上搜索“复合索引,得到的第一个搜索结果的这篇文章就说的就很简单明了:

下面这个SQL语句在 列X,列Y,列Z 上建立了一个复合索引。

CREATE INDEX 索引名 ON 表名(列名X, 列名Y, 列名Z);

其实这相当于建立了三个索引,分别是:

  1. 单列索引(列X)
  2. 复合索引(列X, 列Y)
  3. 复合索引(列X,列Y,列Z)

而Caché/IRIS是不承认最左匹配原则的,Caché/IRIS的原则非常简单粗暴: 既然定义了索引在这些字段上,查询中必须同时有所有这些字段。 也就是说,这个复合索引

CREATE INDEX 索引名 ON 表名(列名X, 列名Y, 列名Z);

单按列名X,或者“列名X and 列名Y”做SQL查询都用不到这个索引。

所以,在了解了Caché/IRIS的原则,或者说吃过亏之后,有些同学想到了这么个变通的法子:

假设您只有上述索引,在这3个字段上没有其他索引,您本来的查询是

SELECT * FROM tablename WHERE 列X ='xxx'

为了用到这个索引,可以改写成

SELECT * FROM tablename WHERE 列X ='xxx' and 列Y in (a,b,c) and 列Z in (a,b,c)

在很多业务场景下,这样的变通是可行的,硬凑一个其实不需要的查询条件并不难。

最后说一句:尽管Caché/IRIS的复合索引不遵循最左匹配,创建索引时ON后面的字段顺序可也不是无所谓的。索引的结构还是一个一级级的树。那个字段在上一级子节点依然非常重要。

0
0 217
文章 Hao Ma · 三月 19, 2024 4m read

正确的使用Bitmap Index (位图索引)来代替普通索引,可以成百上千倍的提高SQL查询性能。

先来看看Bitmap索引和普通索引的区别。我来在Patient表的Sex字段上创建两个索引

  • idxSex: 普通索引
  • bidxSex: bitmap索引

然后创建10个病人数据,查看索引的内容:

# 普通索引
^User.PatientI("idxSex"," F",1)	=	""
^User.PatientI("idxSex"," F",6)	=	""
^User.PatientI("idxSex"," F",8)	=	""
^User.PatientI("idxSex"," M",2)	=	""
^User.PatientI("idxSex"," M",3)	=	""
^User.PatientI("idxSex"," M",4)	=	""
^User.PatientI("idxSex"," M",5)	=	""
^User.PatientI("idxSex"," M",7)	=	""
^User.PatientI("idxSex"," M",9)	=	""
^User.PatientI("idxSex"," M",10)	=	""

# bitmap索引
^User.PatientI("bidxSex"," F",1)	=	$zwc(407,2,1,6,8)/*$bit(2,7,9)*/
^User.PatientI("bidxSex"," M",1)	=	$zwc(413,2,0,1,6,8)/*$bit(3..6,8,10,11)*/

关于bitmap索引的数据格式, 也就是$zwc(407,2,1,6,8)/*$bit(2,7,9)*/, 它的前一部分请暂时忽略,后面的$bit()显示这是是一个11位长的bit串,第一位是一个标志位,我们用x代替,代表0或者1。 后面的10位对应10个病人,从ID=1到ID=10, 那么上面的值可以翻译成

^User.PatientI("bidxSex"," F",1)	=	[x,1,0,0,0,0,1,0,1,0,0]
^User.PatientI("bidxSex"," M",1)	=	[x,0,0,1,1,1,1,0,1,0,1,1]

这样,我们就了解了普通索引和位图索引的区别

  • 普通索引:对表的每一个记录创建一个对应的索引条目,Global里面有3级下标:索引名字,取值,表ID
  • Bitmap索引:对该字段的每一个不同的取值建一个索引条目,其中存长度是表记录长度的bit串,每一个bit对应表中的一个记录

知道了这些, 我们就基本清楚了Bitmap索引的特点和适用:

  • Bitmap索引非常小

    上面的示例中Patient表有10条数据。普通索引有10条记录(这么说不准确,可以理解成一个节点下有10个子节点),而Bitmap索引只有2条。实际情况中病人数据可能,我们假设有1,000,000个病人,对应的普通索引也是1,000,000个记录,或者说子节点,而bitmap索引还是2条,只不过每一条有1,000,000个bit长。由于数据块的长度限制,这1,000,000个长的bit串会被切成64Kbit就是8KB大小的连续的块。

  • Bitmap操作可以非常快

    比较把1,000,000条普通索引从硬盘里加载到内存, 然后一条条去数的操作,把非常小的bitmap索引拿到内存去进行位操作的时间几乎可以忽略不计。 在实践中, 通过用bitmap索引代替普通索引,曾经有过把一个复杂查询从几十秒减小到零点几秒的情况。

  • Bitmap索引适用于数据选择性高的字段。

    文档上的说法是, 如果可能的取值大于10,000到20,000, 最好不要用Bitmap索引。理论上这和表的记录数,字段长度等等都有关系,没有个固定的门限值。而且,实践中很罕见您需要动脑子想某个字段要不要使用Bitmap索引。通常一个字段要不就是高度集中的,比如病人性别,就诊类型,科室,要不就是很分散的值。

    唯一需要斟酌的是日期字段。 如果只看分散程度,1年有365天,10年才365?天,似乎是可以使用bitmap索引。

    我们仔细算算帐。假设这个表10年有1,000,000记录,也就是每天300多条。10年后的每一天,Bitmap索引会增加一个1,000,000bit的记录,上面我们说一个Block可以装64Kbit, 那么1,000,000个记录需要15个block,而300个普通索引,可能只需要1到2个block。

    那么我们就得到一个结论:理论上日期字段不适合使用Bitmap索引;但如果不考虑长远,就为了短时间的查询性能提高,也不是不能用。

然后说说不能用和不合适用Bitmap索引的情况:

  • IDKEY不是正整数

    最常见的不是正整数的IDKEY的场景是父子关系表中的子表。普通的非正整数IDKEY的表,还可以通过添加一个额外的正整数的KEY的方法来回避这个问题。而父子关系表,到目前为止,还是不能用bitmap索引。

    (如果您对数据模型的SQL性能有要求,坚决不要再使用父子关系表)

  • 数据频繁插入删除的表

    举例说,如果表里只有一条记录,插入删除100次后, Bitmap索引需要100个bit来存储。又比如Ensemble中的消息表,通常要保留一个固定时间长度的消息,每天凌晨执行计划任务删除最陈旧的数据。结果就和上面的插入删除100次一样,其中的Bitmap索引会越来越长,性能日趋下降。

    如果您真的要在这样的表上做Bitmap索引,您需要创建任务,定时的清理其中的Bitmap索引。 细节请参考在线文档中的Maintaining Bitmap Indexes

0
0 184
文章 Hao Ma · 三月 19, 2024 3m read

Caché/IRIS的特点是运行Global的修改,而这个修改和SQL是无关的,因此非常容易出现数据库表数据完整性的问题,也就是表中的数据是不是符合定义的表约束。 

这样的情况非常常见。有些是人为的对Global的错误修改, 有些是应用系统的事务性管理写的不对,造成事务回滚的时候破坏了索引的完整性。无论什么原因,只要使用Global操作,破坏SQL的完整性非常难以避免。结果就是SQL查询给出错误结果。

最简单的解决方法就是执行“索引检查(Validate Indices)"

我们来做个实验

- 先修改一个global: 如下图, 将Patient表的一个记录的SEX字段,从'M'改到‘F'. 

运行索引检查, 结果会提示您问题在什么地方。 

0
0 141
文章 Hao Ma · 三月 19, 2024 3m read

上个帖子写了TuneTable的执行, 提到了SQL优化器使用的那些统计数据, 这里逐一的介绍一下这些统计项。了解它们看懂和分析SQL执行计划的基础。 如果您不需要做单个查询的优化工作,可以调过这部分内容。 

表的统计项

  • Extent Size: 表的大小,也就是记录数。在执行多表关联(JOIN)的查询时,SQL优化器会根据Extent Size值,从数据量最小的表来开始执行查询。

您还需要了解:表创建的时候Extent Size会获得一个初始值,而之后的插入修改数据并不自动修改这个值。而只有执行TuneTable才会修改这个。 这也就是为什么没有执行过TuneTable的数据库SQL性能好不了的原因。下图中的Patient表,可以看出有1,000,000记录

字段的统计项

请看下面的图

  • 选择性(Selectivity)

选择性取值可以是1或者一个百分数。取值为1说明这是个unique的字段,比如上图的ID, PatientNumber。 %表示的值,取值越高说明唯一性越低。比如上图中的Name的选择性是1.2987%,说明不是唯一值,有重复的姓名,但比例不高。 相反,Sex的选择性是50%, 说明只有两个取值。 

  • 离散值选择性Outlier Selectivity),

始用于Caché2014.1

0
0 202
文章 Hao Ma · 三月 19, 2024 2m read

IRIS/Caché查询慢,主要原因有以下几个:

  • 应用是一个事务型的数据库, 数据模型的设计不适合某些复杂的分析查询

        这是慢的原因,不是慢的离谱的原因。数据模型是产品设计的范畴, 这里不讨论, 本文只讨论优化。

  • 历史原因,有些表的索引不够优化

        虽然还是设计问题,但可以在实施中或者维护中给出优化方案。

  • 产品运行中的问题造成的查询效率下降

IRIS/Caché数据平台的一个特点是允许跳过SQL约束,对底层数据的直接修改。坏的代码或者应用可能破坏表数据和表索引的约束,造成SQL性能的下降。维护人员应该知道怎么避免,和处理这样的问题。 

  • 维护工作缺乏造成

 比如Tune Table(调整表), 这是必须做的工作,但可惜很有些项目没有执行过。

还有些其他暂时没想到的原因。我会在以下链接的帖子里和各位分享我的参与的一些知识和经验。这些经验是从一些SQL优化的工作中学到的,包括Caché 2010, 2016, IRIS, HealthConnect/Ensemble的项目。比如在最近的一个IRIS项目中, 我和另一个合作伙伴的工程师将IRIS 2021上的HIS数据库的100个SQL查询的平均查询时间从几十秒降低到几秒, 最慢的查询从50分钟降低到10几秒钟。 

0
1 257
文章 Hao Ma · 三月 18, 2024 4m read

TuneTable(调整表)收集数据库中表的统计信息,用来为SQL引擎制定最优的执行计划。在其他数据库产品里,这个动作被称为“gather stats job"或者类似的名字,相比较TuneTable不是那么直白,但作用是一样的。
 

TuneTable是否要人工执行

一定要。

在IRIS 2023版本, 第一次加入了TuneTable的自动执行功能,在此之前的所有IRIS/Caché版本, 如果没有人工执行TuneTable, SQL引擎无法保证给出最好的查询计划。 即使是IRIS2023有了自动执行功能,也还需要人工执行TuneTable的操作,后面解释。

 

怎么知道有没有执行过TuneTable 

到“管理门户>SQL"页面, 打开一个表, 看“目录详情”,如下图, 如果其中的“选择性”,"离群值选择性“, ”离群值“,“平均字段大小”这些字段有数据, 说明这个表至少做过了一次TuneTable. 

除了“字段”按钮页,在“表信息”还有统计项 “ExtentSize", “索引”页,包含每个索引的统计信息项。

关于这些统计项的想象解释, 我会在下个帖子里介绍。 

什么时候执行TuneTable

简单的说:对于查询所用的表,SQL引擎要有以上有统计信息,而且足够准确。

0
0 205
文章 Hao Ma · 三月 6, 2024 2m read

[翻译文章:大型数据集的存储注意事项]这篇文章其实很有用, 但恐怕注意的人不多,特意写文章介绍一下。

USEEXTENTSET翻译过来就是"使用EXTENT集合“,不够直白,它的工作简单说就是:通过哈希类名,使用更短的Global名字

ObjectScript的持久类编译后会默认使用"^类名D" 和"^类名I"的global来存储数据和索引, 当在类定义里加入`Parameter USEEXTENTSET = 1;` 这句话后, 会使用一个自动生成的短类名。 比如*Class User.EMR.MSG.Items.FirstPageCostsItem1*, 默认的存储为类似“^User.EMR.MEC31.FirstPageCoC0D4D”, 使用USEEXTENTSET“后会定义为“^U3Dx.EOXs.1”。

短Global名字的好处 

global名字缩短了,数据和索引的占用并不会改变。改变的是Journal的尺寸。 同样的表和数据插入, 之前的Journal是这样的:

 

使用短global名字后的journal记录是这样的:

 

我的测试中, 使用USEEXTENTSET减少了30%的Journal尺寸。

0
0 114
文章 Qiao Peng · 十二月 7, 2023 5m read

TCP作为OSI 7层的传输层的通信协议,其使用上不像更上层的通信协议那么方便,因为TCP操作的不是数据包,它操作的是数据流。因此有多种将TCP数据流“解释”为数据包(消息)的方法。

InterSystems IRIS提供了多种TCP适配器,用于不同的“解释”,例如EnsLib.TCP.FramedInboundAdapter使用特定的首尾字符做为分隔、EnsLib.TCP.CountedInboundAdapter使用固定的长度进行分隔...

同时,InterSystems IRIS提供了多种开箱即用的TCP业务服务和业务操作,方便接入和发送TCP数据。这里我们介绍常见的使用特定的首尾字符做为分隔的TCP业务服务和业务操作。

1. 通用TCP业务服务和业务操作

EnsLib.TCP.Framed.PassthroughService和EnsLib.TCP.Framed.PassthroughOperation是一组使用特定的首尾字符做为分隔TCP数据流的通用业务服务和业务操作。EnsLib.TCP.Framed.PassthroughService业务服务会将TCP数据封装在Ens.StreamContainer发送给业务流程或业务操作;而EnsLib.TCP.Framed.PassthroughOperation业务操作发送并接收Ens.StreamContainer类型的数据。

0
0 222
文章 Qiao Peng · 十二月 4, 2023 10m read

1. 通用RESTful业务服务和业务操作


InterSystems IRIS 提供了一组通用的RESTful 业务服务和业务操作类,用户无需开发自定义的业务服务和业务操作类,就可以直接向外提供RESTful服务和调用外部的RESTful API。

BS EnsLib.REST.GenericService 通用REST业务服务
BS EnsLib.REST.SAMLGenericService 检查SAML令牌的签名和时间戳的REST业务服务
BO EnsLib.REST.GenericOperation 通用REST业务操作
BO EnsLib.REST.GenericOperationInProc 用于透传模式的通用REST业务操作

2. 通用RESTful 消息

通用的RESTful 业务服务和业务操作类使用一个通用的RESTful消息类 - EnsLib.REST.GenericMessage,它是EnsLib.HTTP.GenericMessage的子类,二者数据结构都是

0
2 227