Engineering Evolution and Optimization of Tencent Docs Microservice Gateway

The web‑gateway of Tencent Docs serves as the traffic entry for the document front‑end and has evolved from a monolithic service to a microservice architecture, but the lack of lock‑file usage caused uncontrolled upgrades of indirect dependencies such as @grpc/grpc-js, leading to excessive CPU usage and service outages.

Initial analysis identified three core problems: (1) the gateway could not lock specific package versions, (2) indirect dependencies were upgraded unintentionally, and (3) the monorepo workspace generated soft/hard links that conflicted with Docker image construction.

To address these issues, the team adopted pnpm workspace for unified package management, which keeps all packages in a single repository while preserving clear boundaries. The workspace also provides hooks ( readPackage and afterAllResolved) to enforce exact versions of critical packages.

Key code snippets used in the solution:

<span>@svr/[email protected] /app</span></code>
<code><span>`-- @wgw/[email protected]</span></code>
<code><span>+-- @opentelemetry/[email protected]</span></code>
<code><span>`-- @grpc/[email protected]</span>

A custom Docker build process was introduced to copy only the necessary microservice files and its dependencies, avoiding the pollution caused by copying the entire repository. The Dockerfile now uses a multi‑stage build with a tailored context:

FROM base AS topdep</code>
<code>WORKDIR /</code>
<code>RUN mkdir node_modules packages</code>
<code>COPY node_modules/ node_modules</code>
<code>COPY packages/ packages</code>
<code>FROM topdep as svr</code>
<code>WORKDIR /usr/app</code>
<code>COPY ["pnpm-*.yaml", ".npmrc", "./"]</code>
<code>COPY "servers/${APP}/" .

The pnpm‑context.mjs script generates a minimal Docker context by selecting only the files required for a specific service:

async function main(cli) {</code>
<code>  const projectPath = dirname(cli.dockerFile);</code>
<code>  const [dependencyFiles, packageFiles, metaFiles] = await Promise.all([</code>
<code>    getFilesFromPnpmSelector(`{${projectPath}}^...`, cli.root, {extraPatterns: cli.extraPatterns}),</code>
<code>    getFilesFromPnpmSelector(`{${projectPath}}`, cli.root, {extraPatterns: cli.extraPatterns.concat([`!${cli.dockerFile}`])}),</code>
<code>    getMetafilesFromPnpmSelector(`{${projectPath}}...`, cli.root, {extraPatterns: cli.extraPatterns})</code>
<code>  ]);</code>
<code>  // copy files into a temporary directory and stream as tar</code>
<code>}

To keep the runtime environment consistent, the project disables the node-linker=hoist option and sets package-import-method=copy, ensuring that Docker images contain real files instead of symlinks.

Soft‑link and hard‑link concepts were leveraged to map files without changing their logical paths, reducing the verification effort after the restructuring.

The final outcome includes fully locked dependency versions, elimination of ghost dependencies, a clean Docker image per microservice, and a simplified, reproducible build pipeline that aligns development and production environments.

In conclusion, systematic engineering improvements—especially adopting pnpm workspace, custom Docker contexts, and lock‑file hooks—significantly reduce maintenance overhead and increase the stability of the microservice gateway.