使用系统软件包

---

本教程介绍如何构建自定义 Knative serving 服务，以将图表说明输入参数转换为 PNG 图片格式的图表。本教程使用已作为系统软件包安装在服务容器环境中的 Graphviz。您可以通过命令行实用程序使用 Graphviz 来处理请求。

目标

• 使用 Dockerfile 编写并构建一个自定义容器
• 编写、构建和部署 Knative serving 服务
• 使用 Graphviz dot 实用程序生成图表
• 通过使用 DOT 语法发布集合中的图表或您自己创建的图表来测试服务

费用

在本文档中，您将使用 Google Cloud 的以下收费组件：

• Cloud Build
• Container Registry
• Knative serving

您可使用价格计算器根据您的预计使用情况来估算费用。 Google Cloud 新用户可能有资格申请免费试用。

注意：Container Registry 已被弃用，并已安排关停。2024 年 1 月 8 日之前未使用 Container Registry 的组织默认在 Artifact Registry 上托管新的 gcr.io 制品库。自 2024 年 5 月 15 日起，之前未使用 Container Registry 的 Google Cloud 项目将仅支持托管和管理 Artifact Registry 中 gcr.io 网域的映像。

Container Registry 计划于 2025 年 3 月 18 日关停。如需详细了解弃用情况，请参阅 Container Registry 弃用。

准备工作

• 本教程假定您已在集群上安装并配置了 Knative serving。
• 确保命令行环境已设置，并且工具为最新：
  • Google Cloud 上的 GKE 集群
  • Google Cloud 外部的 GKE 集群

检索代码示例

如需检索可用的代码示例，请执行以下操作：

1. 将示例应用代码库克隆到本地机器：

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

   或者，您也可以下载该示例的 zip 文件并将其解压缩。

   Python

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

   或者，您也可以下载该示例的 zip 文件并将其解压缩。

   Go

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

   或者，您也可以下载该示例的 zip 文件并将其解压缩。

   Java

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

   或者，您也可以下载该示例的 zip 文件并将其解压缩。

2. 切换到包含 Knative serving 示例代码的目录：

   Node.js

   cd nodejs-docs-samples/run/system-package/

   Python

   cd python-docs-samples/run/system-package/

   Go

   cd golang-samples/run/system_package/

   Java

   cd java-docs-samples/run/system-package/

直观呈现架构

基本架构如下所示：

如需了解图表来源，请参阅 DOT 说明

用户向 Knative serving 服务发出 HTTP 请求，然后该服务执行 Graphviz 实用程序来将请求转换为图片，并将得到的图片以 HTTP 响应形式传递给用户。

了解代码

使用 Dockerfile 定义您的环境配置

要点：在 Dockerfile 中，利用库、实用程序、环境变量、配置文件和启动流程自定义您的环境。这是一种容器化方法，适用于“服务器配置”。

您的 Dockerfile 取决于服务将使用的语言和基础运营环境，例如 Ubuntu。

注意：尽管此快速入门适用于 Knative serving，但它还介绍了各种 Dockerfiles，您可以此为起点为其他服务构建 Dockerfile。

此服务还需要一个或多个其他系统软件包，但这些软件包不会默认提供。

1. 在编辑器中打开 Dockerfile。

2. 查找 Dockerfile RUN 语句。该语句允许运行任意 shell 命令来修改环境。如果 Dockerfile 包含多个阶段（可通过找到多条 FROM 语句来确定），则您将会在最后一个阶段找到这条语句。

   所需的特定软件包及其安装机制因容器内声明的操作系统而异。

   如需获取有关所用操作系统或基础映像的说明，请点击相应的标签页。

   Debian/Ubuntu

   RUN apt-get update -y && apt-get install -y \
     graphviz \
     && apt-get clean

   Alpine

   Alpine 还需要一个用于支持字体的软件包。

   RUN apk --no-cache add graphviz ttf-ubuntu-font-family

   要确定容器映像的操作系统，请检查 FROM 语句中的名称或与基础映像关联的 README 文件。例如，如果您的 Dockerfile 从 node 扩展而来，则可以在 Docker Hub 上找到文档和父级 Dockerfile。

3. 使用 docker build（本地）或 Cloud Build 构建映像，以对您的自定义内容进行测试。

处理传入请求

示例服务使用来自传入 HTTP 请求的参数进行系统调用，以此执行相应的 dot 实用程序命令。

以下 HTTP 处理程序从 dot 查询字符串变量中提取图表说明输入参数。

图表说明包含的字符必须采用网址编码，以便用于查询字符串。

Node.js

app.get('/diagram.png', (req, res) => {
  try {
    const image = createDiagram(req.query.dot);
    res.setHeader('Content-Type', 'image/png');
    res.setHeader('Content-Length', image.length);
    res.setHeader('Cache-Control', 'public, max-age=86400');
    res.send(image);
  } catch (err) {
    console.error(`error: ${err.message}`);
    const errDetails = (err.stderr || err.message).toString();
    if (errDetails.includes('syntax')) {
      res.status(400).send(`Bad Request: ${err.message}`);
    } else {
      res.status(500).send('Internal Server Error');
    }
  }
});

Python

@app.route("/diagram.png", methods=["GET"])
def index():
    """Takes an HTTP GET request with query param dot and
    returns a png with the rendered DOT diagram in a HTTP response.
    """
    try:
        image = create_diagram(request.args.get("dot"))
        response = make_response(image)
        response.headers.set("Content-Type", "image/png")
        return response

    except Exception as e:
        print(f"error: {e}")

        # If no graphviz definition or bad graphviz def, return 400
        if "syntax" in str(e):
            return f"Bad Request: {e}", 400

        return "Internal Server Error", 500

Go

// diagramHandler renders a diagram using HTTP request parameters and the dot command.
func diagramHandler(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodGet {
		log.Printf("method not allowed: %s", r.Method)
		http.Error(w, fmt.Sprintf("HTTP Method %s Not Allowed", r.Method), http.StatusMethodNotAllowed)
		return
	}

	q := r.URL.Query()
	dot := q.Get("dot")
	if dot == "" {
		log.Print("no graphviz definition provided")
		http.Error(w, "Bad Request", http.StatusBadRequest)
		return
	}

	// Cache header must be set before writing a response.
	w.Header().Set("Cache-Control", "public, max-age=86400")

	input := strings.NewReader(dot)
	if err := createDiagram(w, input); err != nil {
		log.Printf("createDiagram: %v", err)
		// Do not cache error responses.
		w.Header().Del("Cache-Control")
		if strings.Contains(err.Error(), "syntax") {
			http.Error(w, "Bad Request: DOT syntax error", http.StatusBadRequest)
		} else {
			http.Error(w, "Internal Server Error", http.StatusInternalServerError)
		}
	}
}

Java

get(
    "/diagram.png",
    (req, res) -> {
      InputStream image = null;
      try {
        String dot = req.queryParams("dot");
        image = createDiagram(dot);
        res.header("Content-Type", "image/png");
        res.header("Content-Length", Integer.toString(image.available()));
        res.header("Cache-Control", "public, max-age=86400");
      } catch (Exception e) {
        if (e.getMessage().contains("syntax")) {
          res.status(400);
          return String.format("Bad Request: %s", e.getMessage());
        } else {
          res.status(500);
          return "Internal Server Error";
        }
      }
      return image;
    });

您需要区分内部服务器错误和无效用户输入。此示例服务会为所有 dot 命令行错误都返回一个内部服务器错误，除非错误消息包含指示用户输入问题的 syntax 字符串。

生成图表

图表生成的核心逻辑是使用 dot 命令行工具将图表说明输入参数处理为 PNG 图片格式的图表。

Node.js

// Generate a diagram based on a graphviz DOT diagram description.
const createDiagram = dot => {
  if (!dot) {
    throw new Error('syntax: no graphviz definition provided');
  }

  // Adds a watermark to the dot graphic.
  const dotFlags = [
    '-Glabel="Made on Cloud Run"',
    '-Gfontsize=10',
    '-Glabeljust=right',
    '-Glabelloc=bottom',
    '-Gfontcolor=gray',
  ].join(' ');

  const image = execSync(`/usr/bin/dot ${dotFlags} -Tpng`, {
    input: dot,
  });
  return image;
};

Python

def create_diagram(dot):
    """Generates a diagram based on a graphviz DOT diagram description.

    Args:
        dot: diagram description in graphviz DOT syntax

    Returns:
        A diagram in the PNG image format.
    """
    if not dot:
        raise Exception("syntax: no graphviz definition provided")

    dot_args = [  # These args add a watermark to the dot graphic.
        "-Glabel=Made on Cloud Run",
        "-Gfontsize=10",
        "-Glabeljust=right",
        "-Glabelloc=bottom",
        "-Gfontcolor=gray",
        "-Tpng",
    ]

    # Uses local `dot` binary from Graphviz:
    # https://graphviz.gitlab.io
    image = subprocess.run(
        ["dot"] + dot_args, input=dot.encode("utf-8"), stdout=subprocess.PIPE
    ).stdout

    if not image:
        raise Exception("syntax: bad graphviz definition provided")
    return image

Go

// createDiagram generates a diagram image from the provided io.Reader written to the io.Writer.
func createDiagram(w io.Writer, r io.Reader) error {
	stderr := new(bytes.Buffer)
	args := []string{
		"-Glabel=Made on Cloud Run",
		"-Gfontsize=10",
		"-Glabeljust=right",
		"-Glabelloc=bottom",
		"-Gfontcolor=gray",
		"-Tpng",
	}
	cmd := exec.Command("/usr/bin/dot", args...)
	cmd.Stdin = r
	cmd.Stdout = w
	cmd.Stderr = stderr

	if err := cmd.Run(); err != nil {
		return fmt.Errorf("exec(%s) failed (%w): %s", cmd.Path, err, stderr.String())
	}

	return nil
}

Java

// Generate a diagram based on a graphviz DOT diagram description.
public static InputStream createDiagram(String dot) {
  if (dot == null || dot.isEmpty()) {
    throw new NullPointerException("syntax: no graphviz definition provided");
  }
  // Adds a watermark to the dot graphic.
  List<String> args = new ArrayList<>();
  args.add("/usr/bin/dot");
  args.add("-Glabel=\"Made on Cloud Run\"");
  args.add("-Gfontsize=10");
  args.add("-Glabeljust=right");
  args.add("-Glabelloc=bottom");
  args.add("-Gfontcolor=gray");
  args.add("-Tpng");

  StringBuilder output = new StringBuilder();
  InputStream stdout = null;
  try {
    ProcessBuilder pb = new ProcessBuilder(args);
    Process process = pb.start();
    OutputStream stdin = process.getOutputStream();
    stdout = process.getInputStream();
    // The Graphviz dot program reads from stdin.
    Writer writer = new OutputStreamWriter(stdin, "UTF-8");
    writer.write(dot);
    writer.close();
    process.waitFor();
  } catch (Exception e) {
    System.out.println(e);
  }
  return stdout;
}

设计安全的服务

dot 工具中的任何漏洞都会成为 Web 服务的潜在漏洞。通过定期重新构建容器映像，您可以使用 graphviz 软件包的最新版本来缓解这种情况。

如果您将当前示例扩展为接受用户输入作为命令行参数，则应防范命令注入攻击。以下是可以防范此类注入攻击的一些方法：

• 将输入映射到由受支持参数组成的字典
• 验证输入是否匹配一系列已知安全的值（可能使用正则表达式）
• 对输入进行转义，以确保不对 shell 语法进行评估

交付代码

如需交付代码，请先使用 Cloud Build 进行构建，然后上传到 Container Registry，最后再部署到 Knative serving：

1. 运行以下命令来构建容器并将其发布到 Container Registry 上。

   Node.js

   gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz

   其中 PROJECT_ID 是您的 Google Cloud 项目 ID，graphviz 是您要为服务指定的名称。

   成功完成后，您将看到一条包含 ID、创建时间和映像名称的 SUCCESS 消息。映像存储在 Container Registry 中，并可根据需要重复使用。

   Python

   gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz

   其中 PROJECT_ID 是您的 Google Cloud 项目 ID，graphviz 是您要为服务指定的名称。

   成功完成后，您将看到一条包含 ID、创建时间和映像名称的 SUCCESS 消息。映像存储在 Container Registry 中，并可根据需要重复使用。

   Go

   gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz

   其中 PROJECT_ID 是您的 Google Cloud 项目 ID，graphviz 是您要为服务指定的名称。

   成功完成后，您将看到一条包含 ID、创建时间和映像名称的 SUCCESS 消息。映像存储在 Container Registry 中，并可根据需要重复使用。

   Java

   此示例使用 Jib 利用常见 Java 工具构建 Docker 映像。无需编写 Dockerfile 或安装 Docker，Jib 便可以优化容器构建。详细了解如何使用 Jib 构建 Java 容器。

   1. 使用 Dockerfile，配置并构建已安装系统软件包的基本映像，以覆盖 Jib 的默认基本映像：

      # Use the Official eclipse-temurin image for a lean production stage of our multi-stage build.
      # https://hub.docker.com/_/eclipse-temurin/
      FROM eclipse-temurin:17.0.12_7-jre
      
      RUN apt-get update -y && apt-get install -y \
        graphviz \
        && apt-get clean

      gcloud builds submit --tag gcr.io/PROJECT_ID/graphviz-base

      其中 PROJECT_ID 是您的 Google Cloud 项目 ID。

   2. 使用 Jib 构建最终容器并在 Container Registry 上发布：

      <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>jib-maven-plugin</artifactId>
        <version>3.4.0</version>
        <configuration>
          <from>
            <image>gcr.io/PROJECT_ID/graphviz-base</image>
          </from>
          <to>
            <image>gcr.io/PROJECT_ID/graphviz</image>
          </to>
        </configuration>
      </plugin>

      mvn compile jib:build \
       -Dimage=gcr.io/PROJECT_ID/graphviz \
       -Djib.from.image=gcr.io/PROJECT_ID/graphviz-base

      其中 PROJECT_ID 是您的 Google Cloud 项目 ID。

2. 使用以下命令进行部署：

   gcloud run deploy graphviz-web --create-if-missing --image gcr.io/PROJECT_ID/graphviz

   其中 PROJECT_ID 是您的 Google Cloud 项目 ID，graphviz 是上述容器的名称，graphviz-web 是服务名称。

   等待部署完成，这可能需要半分钟左右的时间。

3. 如果要将代码更新部署到该服务，请重复执行上述步骤。向服务执行的每次部署都会创建一个新的修订版本，该修订版本准备就绪后会自动开始处理流量。

试试看

要试用您的服务，您可以发送 HTTP POST 请求，并使用 DOT 语法在请求负载中添加说明。

1. 向您的服务发送 HTTP 请求。

   您可以将图表嵌入到网页中：

   1. 如需获取负载均衡器的外部 IP，请运行以下命令：

      kubectl get svc istio-ingressgateway -n ASM-INGRESS-NAMESPACE

      将 ASM-INGRESS-NAMESPACE 替换为 Cloud Service Mesh 入站流量所在的命名空间。如果您使用默认配置安装了 Cloud Service Mesh，请指定 istio-system。

      输出类似于以下内容：

      NAME                   TYPE           CLUSTER-IP     EXTERNAL-IP  PORT(S)
      istio-ingressgateway   LoadBalancer   XX.XX.XXX.XX   pending      80:32380/TCP,443:32390/TCP,32400:32400/TCP

      其中 EXTERNAL-IP 值是负载均衡器的外部 IP 地址。

   2. 通过在网址中使用此 EXTERNAL-IP 地址，运行 curl 命令。 请不要将协议（例如：http://）添加到 SERVICE_DOMAIN 中。

      curl -G -H "Host: SERVICE_DOMAIN" http://EXTERNAL-IP/diagram.png \
         --data-urlencode "dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }" \
         > diagram.png

2. 在任何支持 PNG 文件的应用（如 Chrome）中，打开生成的 diagram.png 文件。

   该属性应如下所示：

   

   来源：DOT 说明

您可以浏览一小部分现成的图表说明。

1. 复制所选 .dot 文件的内容

2. 将其粘贴到 curl 命令中：

   curl -G -H "Host: SERVICE_DOMAIN" http://EXTERNAL-IP/diagram.png \
   --data-urlencode "dot=digraph Run { rankdir=LR Code -> Build -> Deploy -> Run }" \
   > diagram.png

清理

您可以删除为本教程创建的资源，以避免产生费用。

删除教程资源

1. 删除您在本教程中部署的 Knative serving 服务：

   gcloud run services delete SERVICE-NAME

   其中，SERVICE-NAME 是您选择的服务名称。

   您还可以从 Google Cloud 控制台中删除 Knative serving 服务：

   前往 Knative serving

2. 移除您在教程设置过程中添加的 gcloud 默认配置：

    gcloud config unset run/platform
    gcloud config unset run/cluster
    gcloud config unset run/cluster_location
   

3. 移除项目配置：

    gcloud config unset project
   

4. 删除在本教程中创建的其他 Google Cloud 资源：

   • 从 Container Registry 中删除名为 gcr.io/<var>PROJECT_ID</var>/graphviz 的容器映像。
   • 如果您为本教程创建了一个集群，请删除集群。

后续步骤

• 对您的 graphviz 应用进行实验：
  • 添加对其他 graphviz 实用程序的支持，以便运用不同算法来生成图表。
  • 将图表保存到 Cloud Storage。要保存该图片或 DOT 语法吗？
  • 使用 Cloud Natural Language API 实现内容滥用防护。
• 探索有关 Google Cloud 的参考架构、图表和最佳实践。查看我们的 Cloud 架构中心。