当前位置：首页 > news >正文

自托管Notion+GitHub MCP服务器：生产级AI工具调用中枢搭建指南

news 2026/7/9 4:20:21

1. 项目概述：为什么你需要一个自托管的 Notion + GitHub MCP 服务器

你有没有过这种体验：AI 助手在聊天窗口里说得头头是道，“我帮你查了 Notion 里的项目进度”“我看了 GitHub 上那个 PR 的评论”，可一到执行环节，它就卡住了——不是打不开链接，就是权限不足，或者干脆把你的需求翻译成了一段漂亮的废话？这背后缺的不是算力，而是一个真正能“动手干活”的中间人。Model Context Protocol（MCP）服务器，就是这个中间人。它不是另一个聊天界面，而是一套标准化的“AI 工具调用协议”，让大模型能像调用本地函数一样，安全、可靠、可审计地操作你的真实数据源。你可以把它理解成给 AI 装上了一双手：Notion 是它的笔记本和任务看板，GitHub 是它的代码工坊和协作中心。当这两者被整合进一个自托管的 MCP 服务器，你就拥有了一个完全可控的“AI 协作中枢”。

这个项目的核心价值，不在于它有多炫技，而在于它解决了三个现实痛点。第一是控制权。官方的 Notion 或 GitHub MCP 服务固然方便，但它们的数据流向、日志留存、功能开关，全由平台方决定。当你需要调试一个奇怪的 API 错误，或者想确认某个敏感操作是否真的被执行，你只能干等客服回复。而自托管意味着所有日志、所有配置、所有凭证，都躺在你自己的服务器上，随时可查、可改、可审计。第二是组合能力。单个 MCP 服务器只连一个服务，就像只给汽车装一个轮子。而 Notion 管理知识与流程，GitHub 管理代码与协作，两者天然互补。一个能同时理解“这个需求在 Notion 里有详细文档”和“这个功能要改 GitHub 里的 src/utils 目录”的 AI，才是真正的生产力倍增器。第三是工程化落地。很多 AI 集成项目止步于本地 demo，一旦涉及多用户、权限隔离、流量管控、故障恢复，就立刻崩盘。这个项目从第一天起，就把 OAuth 2.1 认证、多租户隔离、细粒度限流、结构化审计日志、Kubernetes 编排这些生产级要素，作为不可妥协的基石。它不是一个玩具，而是一份可直接用于小团队内部提效的、经过实战检验的工程蓝图。

我本人就是这个项目的亲历者和主要构建者。整个过程没有黑魔法，只有大量踩坑后的经验沉淀。比如，OAuth 2.1 的 PKCE 流程，官方文档写得云山雾罩，但实际实现时，你必须亲手生成 code_verifier 和 code_challenge，并确保它们在重定向跳转的整个生命周期里不丢失、不混淆；再比如，Rate Limiting 不是简单加个中间件就完事，你得想清楚：是按 IP 限？按用户 Session 限？还是按具体工具（如notion.create_page）限？每种策略背后，是对业务场景的深刻理解。这篇文章，就是我把这几个月里，在深夜调试日志、在 Kubernetes Dashboard 里追踪 Pod 崩溃、在 Grafana 图表中定位性能瓶颈时所获得的所有一手经验，毫无保留地拆解给你看。它不讲空泛的“未来已来”，只告诉你今天下午三点，你该在docker-compose.yml里写哪一行，该在express-rate-limit的配置里填哪个数字，以及，当你的 AI 助手第一次成功地在 Notion 里创建了一个页面、又在 GitHub 里提了一个 PR 时，那种“原来我真的做到了”的踏实感，究竟是怎么来的。

2. 整体架构设计与核心思路拆解

2.1 为什么选择 Node.js + Express 作为技术栈？

在项目启动之初，我面前摆着一堆选项：Python 的 FastAPI、Go 的 Gin、甚至 Rust 的 Axum。最终选定 Node.js + Express，绝非因为它是“最火”的，而是因为它在“快速验证”和“生态成熟度”之间，找到了一个对 MCP 这类 I/O 密集型网关服务而言，近乎完美的平衡点。MCP 服务器的本质，是一个高并发、低计算、强依赖外部 API 的代理层。它的核心工作不是做矩阵运算，而是高效地发起 HTTP 请求、处理 JSON 数据、管理会话状态。Node.js 的事件驱动、非阻塞 I/O 模型，天生就为这种场景而生。一个 Express 应用，轻松就能支撑数千个并发连接，而内存占用却远低于同等负载下的 Python 进程。

更重要的是，生态的成熟度直接决定了开发效率。Notion 官方提供了极其完善的 TypeScript SDK，它不仅封装了所有 REST API，还内置了类型定义、错误处理和重试逻辑。GitHub 方面，Octokit 是无可争议的事实标准，它对 GraphQL 和 REST API 的支持都极为完备，且社区维护活跃。这意味着，当我需要实现search_notion这个工具时，我无需从零开始构造 HTTP 请求头、解析响应体、处理分页，只需几行代码：

import { Client as NotionClient } from '@notionhq/client'; const notion = new NotionClient({ auth: userToken }); // 一行代码，完成搜索，SDK 自动处理分页和错误 const response = await notion.search({ query: 'Q3 OKR', filter: { property: 'object', value: 'page' } });

如果换成一门新语言，光是搞定这两个 SDK 的兼容性、认证流程和类型系统，就可能耗费数周时间。而用 Node.js，我可以在一天之内，就跑通从用户授权、获取 token、到成功调用notion.pages.create的完整链路。这为后续的复杂功能——比如多租户隔离、审计日志、Kubernetes 部署——赢得了宝贵的时间窗口。当然，Node.js 并非没有缺点。JavaScript 的单线程特性意味着 CPU 密集型任务（如大规模数据转换）会阻塞整个事件循环。但在 MCP 场景下，这类任务几乎不存在。因此，这个选择是典型的“用正确的工具，解决正确的问题”，而非盲目追逐技术潮流。

2.2 “单服务器双协议”架构的取舍与优势

将 Notion 和 GitHub 的 MCP 服务合并到一个进程中，是我做的第二个关键决策，也是最容易被质疑的。常见的做法是部署两个独立的服务，然后让 AI 客户端（如 Cursor）通过配置文件，分别指定notion-mcp-server:8080和github-mcp-server:8081。这看起来更“模块化”，也更符合微服务的教条。但我坚持单服务器，是基于对运维成本和用户体验的残酷计算。

运维成本上，两个服务意味着两套独立的生命周期管理：你得为每个服务单独编写 Dockerfile、维护各自的环境变量、配置两套监控告警、处理两套日志收集。当 GitHub 的 API 发生变更，你需要更新并测试两个服务的 Octokit 版本；当 Notion 推出新的数据库权限模型，你又得同步修改两个地方的 SDK 调用逻辑。这不仅仅是工作量翻倍，更是故障点的翻倍。一次配置失误，可能导致一个服务正常，另一个服务静默失败，而排查起来却异常困难。

用户体验上，对终端用户（也就是使用 AI 助手的人）而言，“配置一个 URL 和一个 Token”比“配置两个 URL、两个 Token，还要搞清楚哪个工具该走哪个地址”要友好得多。更重要的是，它为未来的“跨服务协同”埋下了伏笔。想象这样一个场景：AI 助手收到指令“把 Notion 里‘待评审’数据库中的所有新任务，同步为 GitHub Issues”。在一个单服务器架构下，这个指令可以被解析为一个原子性的、内部的事务：服务器先调用notion.databases.query获取任务列表，然后在同一个请求上下文中，循环调用github.issues.create创建 Issue。整个过程对客户端是透明的，它只需要发送一次请求。而在双服务器架构下，这需要客户端自己协调两次网络调用，中间任何一步失败，都会导致数据不一致，而这种不一致的修复逻辑，会变得极其复杂。

当然，这个决策也带来了挑战，最主要的就是代码组织的清晰性。我采用了一种“领域驱动”的分层方式：最底层是clients/目录，里面是notion-client.ts和github-client.ts，它们只负责与各自 API 的通信，不包含任何业务逻辑；中间层是tools/目录，里面是notion-tools.ts和github-tools.ts，它们定义了所有 MCP 工具的签名（输入参数、输出格式），并调用底层 client；最上层是routes/目录，里面的tool-router.ts负责将/tools/notion/search这样的路径，精准地路由到notion-tools.search()函数。这种分层，确保了即使功能越来越多，代码依然像一本结构清晰的说明书，而不是一团乱麻。

2.3 生产级安全模型的顶层设计

安全不是在项目快上线时才加上的“防护罩”，而是从第一行代码就开始编织的“基因”。对于一个连接着用户最核心数据（笔记、代码）的 MCP 服务器，我设计了三层纵深防御体系，每一层都针对一个明确的威胁模型。

第一层是对外部 API 的访问控制，即我们如何安全地代表用户去调用 Notion 和 GitHub。这里，OAuth 2.1 是唯一的选择。我坚决摒弃了“让用户直接提供 API Key”的捷径，因为那等于把家门钥匙交给了 AI 助手。OAuth 2.1 的核心价值在于“最小权限原则”和“动态令牌”。当用户点击“连接 Notion”时，他看到的是 Notion 官方的授权页面，上面清晰地列出了我的应用将获得哪些权限（例如，“读取和编辑你的页面”）。用户批准后，Notion 返回的不是一个永久有效的密钥，而是一个有时效性的access_token。这个 token 可以被撤销，其权限范围是固定的，且无法用来登录用户的 Notion 账户。我在实现时，严格遵循了 OAuth 2.1 的强制要求：禁用隐式授权（Implicit Grant），全程使用授权码（Authorization Code）流程，并为每一次授权请求都生成唯一的code_verifier和code_challenge，彻底杜绝了中间人窃取授权码的风险。

第二层是对 MCP 服务器自身的访问控制，即如何防止未经授权的 AI 客户端随意调用我们的工具。这层保护，我称之为“客户端认证”。它和第一层是正交的：第一层管“服务器能不能代表用户做事”，第二层管“谁有资格让服务器做事”。我采用了轻量级的 API Key + Session Token 混合模式。在用户完成 OAuth 授权后，服务器会为该用户生成一个唯一的、随机的session_id（例如，一个 32 字节的 UUID），并将其存储在 Redis 中，关联到该用户的 OAuth tokens。此后，AI 客户端在每次调用工具时，都必须在请求头中携带X-Session-ID: <session_id>。服务器接收到请求后，第一步不是去调用 Notion，而是先查询 Redis，验证这个session_id是否存在、是否有效、是否属于当前请求的用户。这一步，将非法调用拦截在了业务逻辑之外，极大地降低了攻击面。

第三层是运行时的隔离与审计，这是多租户场景下的生命线。它的目标是确保“Alice 的请求，永远只能使用 Alice 的 token，永远只能访问 Alice 的数据”。这听起来理所当然，但在代码实现中，一个疏忽就可能导致灾难。我为此设定了两条铁律：第一，“绝不信任客户端传来的任何标识符”。客户端可能会在请求体里附带一个user_id，但服务器绝不会直接相信它，而是必须通过session_id去 Redis 中查出真实的user_id和对应的 tokens。第二，“所有外部 API 调用，必须显式地注入凭据”。在notion-tools.ts的每一个函数里，你都能看到类似const notion = createNotionClient(userTokens.notion)的代码。这个createNotionClient函数，每次都会根据传入的 token 创建一个全新的、独立的 SDK 实例。这杜绝了全局单例 client 因为状态污染而导致的“越权调用”。正是这些看似繁琐的细节，共同构成了一个坚不可摧的安全基座。

3. 核心功能模块详解与实操要点

3.1 OAuth 2.1 认证流程的完整实现

OAuth 2.1 的实现，是整个项目中最容易出错、也最考验细节的地方。我将整个流程拆解为四个精确的步骤，并给出每个步骤中你绝对不能忽略的关键点。

第一步：注册 OAuth 应用并获取凭证

这不是一个简单的“复制粘贴”操作。对于 GitHub，你需要进入Settings > Developer settings > OAuth Apps，创建一个新的 OAuth App。关键点在于Homepage URL和Authorization callback URL的填写。Homepage URL可以是你 MCP 服务器的根域名，例如https://mcp.yourcompany.com。而Authorization callback URL必须是你的服务器上一个具体的、你已经实现了的路由，例如https://mcp.yourcompany.com/auth/github/callback。绝对不要在这里填写http://localhost:3000之类的开发地址，因为生产环境的回调必须匹配。同样，对于 Notion，你需要在https://www.notion.so/my-integrations页面创建一个 Integration，并在OAuth Redirect URLs中填入https://mcp.yourcompany.com/auth/notion/callback。此时，你会得到一对Client ID和Client Secret。请立即将Client Secret存入你的 Kubernetes Secret 中，永远不要将其硬编码在package.json或.env文件里，哪怕是在开发环境。

第二步：发起授权请求（Login Endpoint）

当用户点击“连接 GitHub”按钮时，前端会向你的服务器发起一个 GET 请求，例如/auth/github/login。你的 Express 路由处理器需要做三件事：

生成 PKCE 凭据：使用crypto模块生成一个随机的code_verifier（推荐 32 字节），然后用 SHA256 对其进行哈希，并进行 Base64Url 编码，得到code_challenge。
构造重定向 URL：将code_challenge、code_challenge_method=S256、response_type=code、client_id、scope（例如repo,user:email）和state（一个随机字符串，用于防止 CSRF）拼接到 GitHub 的授权 URL 上：https://github.com/login/oauth/authorize?...。
存储临时状态：将code_verifier和state一起，以state为 key，存入 Redis，设置一个较短的过期时间（例如 10 分钟）。这是为了在回调时，能够验证code_verifier的合法性。

// /auth/github/login app.get('/auth/github/login', (req, res) => { const state = crypto.randomBytes(16).toString('hex'); const codeVerifier = crypto.randomBytes(32).toString('base64url'); const codeChallenge = crypto .createHash('sha256') .update(codeVerifier) .digest('base64url'); // 将 verifier 和 state 存入 Redis redis.setex(`oauth:${state}`, 600, codeVerifier); const githubAuthUrl = new URL('https://github.com/login/oauth/authorize'); githubAuthUrl.searchParams.set('client_id', GITHUB_CLIENT_ID); githubAuthUrl.searchParams.set('redirect_uri', 'https://mcp.yourcompany.com/auth/github/callback'); githubAuthUrl.searchParams.set('state', state); githubAuthUrl.searchParams.set('scope', 'repo,user:email'); githubAuthUrl.searchParams.set('code_challenge', codeChallenge); githubAuthUrl.searchParams.set('code_challenge_method', 'S256'); res.redirect(githubAuthUrl.toString()); });

第三步：处理授权回调（Callback Endpoint）

GitHub 在用户授权后，会将浏览器重定向到你指定的callbackURL，并附带?code=ABC&state=XYZ。你的/auth/github/callback路由必须严格验证state，并用它从 Redis 中取出code_verifier，然后向 GitHub 的令牌端点发起一个 POST 请求，交换access_token。

// /auth/github/callback app.get('/auth/github/callback', async (req, res) => { const { code, state } = req.query; if (!code || !state) { return res.status(400).send('Missing code or state'); } // 1. 验证 state const storedVerifier = await redis.get(`oauth:${state}`); if (!storedVerifier) { return res.status(400).send('Invalid or expired state'); } // 2. 向 GitHub 令牌端点发起请求 const tokenResponse = await axios.post( 'https://github.com/login/oauth/access_token', new URLSearchParams({ client_id: GITHUB_CLIENT_ID, client_secret: GITHUB_CLIENT_SECRET, code: code as string, state: state as string, code_verifier: storedVerifier, redirect_uri: 'https://mcp.yourcompany.com/auth/github/callback' }), { headers: { Accept: 'application/json' } } ); const { access_token, scope, token_type } = tokenResponse.data; if (!access_token) { return res.status(400).send('Failed to get access token'); } // 3. 创建用户会话 const userId = generateUserId(); // 例如，从 GitHub token 解析出 user_id const sessionId = crypto.randomBytes(16).toString('hex'); // 将用户信息和 tokens 存入 Redis await redis.setex( `session:${sessionId}`, 3600, // 1小时 JSON.stringify({ userId, github: { accessToken: access_token, scope }, notion: null // Notion token 为空，等待用户连接 }) ); // 4. 重定向回前端，带上 session_id res.redirect(`https://your-frontend.com/success?session_id=${sessionId}`); });

第四步：在工具调用中使用 Token

当 AI 客户端带着X-Session-ID头调用/tools/github/create_issue时，你的工具函数必须首先从 Redis 中加载该 session，并从中提取出github.accessToken，然后将其注入到 Octokit 实例中。

// tools/github-tools.ts export async function createIssue( params: { repo: string; title: string; body: string }, session: SessionData // 从中间件中解析出的 session 对象 ): Promise<any> { // 1. 从 session 中获取 GitHub token const githubToken = session.github?.accessToken; if (!githubToken) { throw new Error('GitHub not authorized for this user'); } // 2. 创建一个专属的 Octokit 实例 const octokit = new Octokit({ auth: githubToken }); // 3. 执行 API 调用 const [owner, repoName] = params.repo.split('/'); const response = await octokit.rest.issues.create({ owner, repo: repoName, title: params.title, body: params.body }); return response.data; }

提示：在生产环境中，session对象应该由一个专门的中间件（例如authenticateSession）在所有/tools/*路由之前加载并挂载到req.session上。这样，所有的工具函数都可以无感知地使用它，保证了代码的复用性和安全性。

3.2 多租户隔离机制的深度剖析

多租户不是“支持多个用户”这么简单，它是一场关于数据边界的精密手术。核心思想是：在任何时刻，任何代码路径，都不能存在一个全局变量或单例对象，其状态可能被不同用户的请求所共享。我将其实现分为数据存储、会话管理和代码执行三个层面。

数据存储层：Redis 作为租户状态的黄金标准

我放弃了关系型数据库（如 PostgreSQL）作为主存储，选择了 Redis。原因很简单：Redis 的key结构天然支持多租户。每一个用户的状态，都以session:<uuid>的形式存储。<uuid>就是租户的唯一身份标识。当一个请求到来时，中间件authenticateSession的工作流程是：

从请求头X-Session-ID中提取sessionId。
执行GET session:<sessionId>命令。
如果返回null，则拒绝请求（HTTP 401）。
如果返回一个 JSON 字符串，则JSON.parse它，并将其挂载到req.session上。

这个过程是原子的、快速的、且完全隔离的。Alice 的session:a1b2c3和 Bob 的session:d4e5f6在 Redis 中是两个完全独立的 key，没有任何交集。更重要的是，Redis 的EXPIRE命令可以为每个 key 设置精确的过期时间，这完美契合了 Session 的生命周期管理。相比之下，如果用 PostgreSQL，你需要为每个 Session 记录一个user_id字段，然后在每次查询时都加上WHERE user_id = ?的条件。这不仅增加了 SQL 的复杂度，也引入了因程序员疏忽而遗漏WHERE条件的巨大风险。

会话管理层：“Session ID” 是唯一的通行证

在 MCP 的上下文中，“用户”不是一个抽象概念，而是一个具体的、可验证的Session ID。这个 ID 是整个多租户体系的基石。它必须满足三个条件：唯一性、随机性、不可预测性。我使用crypto.randomBytes(16).toString('hex')来生成它，这比Math.random()或Date.now()生成的 ID 安全得多。这个 ID 一旦生成，就成为用户与服务器之间所有交互的“护照”。AI 客户端在配置时，只需要记住这个字符串，并在每次请求中携带它。服务器不需要知道这个 ID 对应的是 Alice 还是 Bob，它只需要知道，这个 ID 在 Redis 中有对应的、有效的记录即可。这种设计，将身份认证（Authentication）和授权（Authorization）解耦了。认证由authenticateSession中间件完成，而授权（例如，判断用户是否有权调用notion.create_page）则由具体的工具函数在运行时，根据session对象中存储的notion.token是否存在来决定。

代码执行层：“凭据注入”是防越权的最后防线

这是最容易被忽视，也最致命的一环。假设你有一个全局的notionClient实例，它在应用启动时就用一个固定的 token 初始化好了。那么，无论哪个用户的请求进来，调用的都是同一个 client，结果必然是所有用户都在操作同一个 Notion 工作区，造成灾难性的数据混杂。我的解决方案是“凭据注入”（Credential Injection）。在tools/notion-tools.ts中，每一个导出的函数，其第一个参数都是session: SessionData。这个session对象，包含了该用户专属的notion.accessToken。函数内部，会立即用这个 token 创建一个新的NotionClient实例：

// tools/notion-tools.ts import { Client as NotionClient } from '@notionhq/client'; export async function searchPages( params: { query: string }, session: SessionData ): Promise<any> { // 关键！每次都用 session 中的 token 创建新实例 const notion = new NotionClient({ auth: session.notion?.accessToken }); if (!notion) { throw new Error('Notion not authorized for this user'); } return await notion.search({ query: params.query }); }

这种模式，确保了每一次 API 调用，都是在严格的租户上下文中进行的。即使session.notion.accessToken是undefined，函数也会抛出一个清晰的错误，而不是静默失败或调用错误的 token。这是一种“防御性编程”，它让错误在最早、最明确的地方暴露出来，而不是在 Notion API 返回一个模糊的401 Unauthorized时才被发现。

3.3 细粒度速率限制的策略与配置

express-rate-limit是一个优秀的库，但它默认的“按 IP 限流”策略，在 MCP 场景下是远远不够的。一个恶意的 AI 客户端，完全可以伪造不同的 IP 地址来绕过限制。因此，我实现了两级限流：全局基础限流和租户级精细限流。

全局基础限流：守门员

这是第一道防线，目的是防止 DDoS 攻击和粗暴的暴力探测。我配置了一个非常宽松的规则，仅针对/tools/*路径：

import rateLimit from 'express-rate-limit'; const globalLimiter = rateLimit({ windowMs: 60 * 60 * 1000, // 1小时 max: 1000, // 每小时最多1000次 message: 'Too many requests from this IP, please try again later.', standardHeaders: true, legacyHeaders: false, }); // 仅对工具调用路径启用 app.use('/tools', globalLimiter);

这个配置的意义在于，它不关心你是谁，只关心你的 IP 在过去一小时内发了多少请求。1000 次/小时，相当于平均 3.6 秒一次，这对于一个正常的、有节奏的 AI 工作流来说，是绰绰有余的。但对于一个试图每秒发起 100 次请求的脚本，它会在几分钟内就被封禁。这个限流器是“无状态”的，它使用内存存储，因此在 Kubernetes 的多副本部署中，每个 Pod 都有自己的计数器。这虽然不是完全精确的全局计数，但对于抵御初级攻击已经足够。

租户级精细限流：裁判员

这才是真正体现业务逻辑的地方。它基于X-Session-ID，对每个租户的请求进行独立计数。我使用了rate-limit-redis这个库，它能利用 Redis 的原子操作，实现跨 Pod 的精确计数。

import RedisStore from 'rate-limit-redis'; import rateLimit from 'express-rate-limit'; const tenantLimiter = rateLimit({ store: new RedisStore({ client: redis, // 复用你的 Redis 客户端 }), windowMs: 15 * 60 * 1000, // 15分钟 max: (req: Request) => { // 根据请求路径，返回不同的限额 const path = req.path; if (path.includes('notion/search')) return 100; // 搜索操作，频率高 if (path.includes('notion/create_page')) return 20; // 创建页面，频率低 if (path.includes('github/create_issue')) return 30; // 创建 Issue，频率中等 return 50; // 默认限额 }, keyGenerator: (req: Request) => { // 关键！使用 session_id 作为 key，而非 IP return req.headers['x-session-id'] as string; }, message: 'You have exceeded your request limit for this tool.', standardHeaders: true, legacyHeaders: false, }); // 在所有工具路由之前应用 app.use('/tools', tenantLimiter);

这个配置的精妙之处在于max函数和keyGenerator函数。keyGenerator确保了计数器是按X-Session-ID维护的，从而实现了租户隔离。而max函数则允许你根据具体的工具路径，动态地设定不同的限额。为什么notion/search的限额是 100，而notion/create_page只有 20？因为搜索是一个只读、低开销的操作，AI 助手可能会频繁地扫描数据库；而创建页面是一个写操作，它会触发 Notion 的通知、影响数据库的排序，对 API 的压力更大，也更容易被滥用。这种差异化的策略，体现了对业务本质的理解，而不是一刀切的粗暴管理。

注意：在生产环境中，redis客户端必须配置连接池，以避免限流器本身成为性能瓶颈。我通常会为限流器配置一个独立的、连接数较小的 Redis 连接池，与主业务的 Redis 连接池分开，确保限流功能的稳定性不会影响到核心的数据读写。

4. 生产级部署与可观测性实践

4.1 Docker 化构建与 Kubernetes 部署详解

容器化不是为了赶时髦，而是为了消灭“在我机器上是好的”（It Works on My Machine）这个万恶之源。一个精心编写的 Dockerfile，就是一份可执行的、精确到字节的环境说明书。

Dockerfile 的关键实践

我的Dockerfile遵循了最佳实践的几个核心原则：多阶段构建、最小化基础镜像、运行时非 root 用户、环境变量注入。

# 构建阶段：使用完整的 node:18-slim 镜像 FROM node:18-slim AS builder # 创建一个非 root 用户，用于构建 RUN groupadd -g 1001 -f nodejs && useradd -S -u 1001 -U nodejs USER nodejs # 设置工作目录 WORKDIR /home/nodejs/app # 复制 package.json 和 lock 文件，利用 Docker 缓存 COPY --chown=nodejs:nodejs package*.json ./ RUN npm ci --only=production # 复制源代码 COPY --chown=nodejs:nodejs . . # 生产阶段：使用更小的 alpine 镜像 FROM node:18-alpine # 创建运行用户 RUN addgroup -g 1001 -f nodejs && adduser -S nextjs -u 1001 # 复制构建好的 node_modules 和源代码 COPY --from=builder --chown=nextjs:nodejs /home/nodejs/app/node_modules ./node_modules COPY --from=builder --chown=nextjs:nodejs /home/nodejs/app/src ./src COPY --from=builder --chown=nextjs:nodejs /home/nodejs/app/package*.json ./package*.json # 切换到非 root 用户 USER nextjs # 暴露端口 EXPOSE 8080 # 设置环境变量 ENV NODE_ENV=production ENV PORT=8080 # 启动命令 CMD ["npm", "start"]

这个Dockerfile的亮点在于：

多阶段构建：builder阶段包含了所有构建依赖（如npm install），而最终的alpine阶段只复制了node_modules和源代码，镜像体积从几百 MB 直接压缩到几十 MB。
非 root 用户：USER nextjs确保了容器内的进程以一个权限受限的用户身份运行，即使容器被攻破，攻击者也无法轻易获得宿主机的 root 权限。
环境变量注入：PORT和NODE_ENV在构建时就已确定，避免了在运行时通过-e参数传递的混乱。

Kubernetes Manifests 的核心组件

一个健壮的 Kubernetes 部署，离不开四个核心 YAML 文件：Deployment、Service、Ingress和Secret。

Deployment定义了应用的副本数、健康检查和滚动更新策略。其中，livenessProbe和readinessProbe是灵魂：

# deployment.yaml apiVersion: apps/v1 kind: Deployment metadata: name: mcp-server spec: replicas: 3 # 3个副本，保证高可用 selector: matchLabels: app: mcp-server template: metadata: labels: app: mcp-server spec: containers: - name: mcp-server image: your-registry/mcp-server:latest ports: - containerPort: 8080 envFrom: - configMapRef: name: mcp-config # 加载非敏感配置 - secretRef: name: mcp-secrets # 加载敏感凭证 livenessProbe: httpGet: path: /healthz port: 8080 initialDelaySeconds: 30 periodSeconds: 10 readinessProbe: httpGet: path: /readyz port: 8080 initialDelaySeconds: 5 periodSeconds: 5

/healthz和/readyz是两个独立的健康检查端点。/healthz检查的是应用的“存活”状态，例如，它会尝试连接 Redis，如果 Redis 不可用，它就返回 500，K8s 会杀死并重启这个 Pod。/readyz检查的是应用的“就绪”状态，例如，它会检查 Rate Limiter 是否已初始化，如果未初始化，它就返回 500，K8s 会暂时将该 Pod 从 Service 的负载均衡池中剔除，直到它返回 200。这种分离，确保了流量只会被导向真正准备就绪的实例。

Ingress则是通往外部世界的门户。我使用cert-manager来自动管理 TLS 证书：

# ingress.yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: mcp-ingress annotations: cert-manager.io/cluster-issuer: "letsencrypt-prod" spec: tls: - hosts: - mcp.yourcompany.com secretName: mcp-tls-secret rules: - host: mcp.yourcompany.com http: paths: - path: / pathType: Prefix backend: service: name: mcp-service port: number: 8080

Secret是存储敏感信息的唯一合法场所。mcp-secrets这个 Secret，包含了GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、NOTION_INTEGRATION_TOKEN等所有密钥。在Deployment中，它们被以环境变量的形式注入到容器中，而不会出现在任何日志或kubectl describe的输出里。