# 部署到 k3s paper-doc 的 MCP 服务跑在 k3s 里,命名空间 **`paper-doc`**,客户端通过 `http://192.168.1.88:30931/mcp` 连接。 > **为什么不是 `paper_doc`**:Kubernetes 的命名空间名必须是 RFC 1123 label, > 下划线不在允许的字符集里(`[a-z0-9]([-a-z0-9]*[a-z0-9])?`),API Server 会直接拒绝。 > 所以命名空间用连字符 `paper-doc`;数据库名和表名仍然是 `paper_doc`,两者不冲突。 ## 部署了什么 | 资源 | 名字 | 说明 | |---|---|---| | Namespace | `paper-doc` | `deploy/k8s/00-namespace.yaml` | | Deployment | `paper-doc-mcp` | 1 副本,跑 MCP 服务的 http 传输 | | Service | `paper-doc-mcp` | NodePort **30931** → 容器 8931 | | ConfigMap | `paper-doc-config` | 非敏感环境变量(数据库地址、监听配置) | | Secret | `paper-doc-secrets` | `DB_USER` / `DB_PASSWORD` / `MCP_HTTP_TOKEN` | | Secret | `aliyun-acr` | 镜像仓库拉取凭证(从 `default` 复制) | 镜像:`registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v5` (`sha256:1e17a72ca611a498d93fc960a7fe1eba5ed5803376794efa66f1967830d51c5d`; `kubectl -n paper-doc get pods -o jsonpath='{.items[0].status.containerStatuses[0].imageID}'` 对得上,才说明跑的就是 ACR 上那一版。历史:v1 首发布 → v2 重命名表 → v3 参考文献库 → v4 补参考文献 MCP 工具 → **v5 换行与参考文献表**。) **数据库**:TiDB 已经在这个集群里,Deployment 用集群内的 Service `tidb-tidb.tidb:4000`,而不是宿主机用的 NodePort `192.168.1.88:32738`。 两者是同一份数据;集群内用 Service 的好处是节点地址变了也不用改配置。 ## 访问地址 | 从哪里连 | 地址 | |---|---| | 宿主机 / 局域网 | `http://192.168.1.88:30931/mcp` | | 集群内 Pod | `http://paper-doc-mcp.paper-doc.svc.cluster.local:8931/mcp` | | 健康检查(免鉴权) | `http://192.168.1.88:30931/healthz`、`/readyz` | 除 `/healthz` 和 `/readyz` 外,所有请求都要带 `Authorization: Bearer `,否则返回 `401`。 Token 在 Secret 里,取法: ```bash export KUBECONFIG=$HOME/.kube/config kubectl -n paper-doc get secret paper-doc-secrets \ -o jsonpath='{.data.MCP_HTTP_TOKEN}' | base64 -d; echo ``` ## 日常操作 先记住这一句,否则 `kubectl` 会去读 root-only 的 `/etc/rancher/k3s/k3s.yaml` 并报 permission denied: ```bash export KUBECONFIG=$HOME/.kube/config ``` ```bash # 状态 kubectl -n paper-doc get deploy,svc,pods kubectl -n paper-doc logs deploy/paper-doc-mcp --tail=50 # 重新构建并推送镜像(需要一个 tag,见下面「两个坑」) deploy/build-mcp-image.sh v3 # 发布新版本 kubectl -n paper-doc set image deployment/paper-doc-mcp \ mcp=registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v3 kubectl -n paper-doc rollout status deployment/paper-doc-mcp # 回滚 kubectl -n paper-doc rollout undo deployment/paper-doc-mcp # 改配置 / 换 token kubectl -n paper-doc edit configmap paper-doc-config kubectl -n paper-doc create secret generic paper-doc-secrets \ --from-literal=DB_USER='Govin' \ --from-literal=DB_PASSWORD='' \ --from-literal=MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \ --dry-run=client -o yaml | kubectl apply -f - kubectl -n paper-doc rollout restart deployment/paper-doc-mcp ``` **验证部署**——不是看 Pod 是不是 Running,而是真的用 MCP 客户端跑一遍: ```bash cd backend .venv/bin/python scripts/smoke_mcp.py \ --url http://192.168.1.88:30931/mcp --token "$(cat /tmp/paper-mcp-token)" # 47 项检查全过 = 集群里这套东西真的能写论文 ``` ## 构建:为什么是 DinD Pod 这台宿主机上没有容器运行时——k3s 用的是 containerd,节点上的 `ctr` / `crictl` 都是 k3s 的软链,谁都不能从 Dockerfile 构建。所以构建放在集群里一个临时的 docker-in-docker Pod 里做,源码通过 hostPath 挂进去(`/workspace`), 这样构建上下文就是当前工作区,未提交的改动也在里面。 `deploy/build-mcp-image.sh` 把这一整套包好了:起 Pod → 登录 → 构建 → 推送 → 删 Pod (`trap` 保证失败也会删)。**仓库凭证是从集群里已有的 `aliyun-acr-secret` 读出来的**, 所以脚本里没有任何密码,也不会进 shell history。 ## 两个坑(都踩过了,别再踩) **1. 镜像 tag 复用会发布不出新代码。** Deployment 的 `imagePullPolicy: IfNotPresent`,节点按 tag 缓存镜像。 用同样的 `:v1` 重新构建推送后,Pod 重启拿到的还是旧镜像—— 现象是新 Pod 起来了、但行为跟没改一样。**每次构建换一个 tag**(v2、v3…), 或者临时把 `imagePullPolicy` 改成 `Always`(代价是每次启动都要连仓库)。 **2. 源码权限 0600 会让容器读不到代码。** 工作区的文件是 `rw-------`,`COPY` 会把权限一起带进镜像, 于是非 root(uid 10001)的容器启动即 `can't open file '/app/scripts/mcp_server.py': [Errno 13] Permission denied`, 然后 CrashLoopBackOff。Dockerfile 里 `RUN chmod -R a+rX /app` 解决—— 镜像里的东西只需要可读,不需要任何人可写。 ## 探针:为什么是两个 | 探针 | 路径 | 语义 | |---|---|---| | liveness | `/healthz` | 进程还活着吗——不碰数据库,所以数据库抖一下不会变成反复重启 | | readiness | `/readyz` | 现在能服务吗——执行 `SELECT 1`,TiDB 不通就把 Pod 摘出 Service,通了自动加回来 | 失败 readiness 只是把 Pod 从负载均衡里摘掉,失败 liveness 会杀掉进程。 数据库短暂不可用只应该是前者,所以这个分工是刻意的。 ## 还没有部署的 - **REST API**:同一个镜像,换 command 即可(`uvicorn app.main:app --host 0.0.0.0 --port 8000`), 再加一个 init 容器跑 `alembic upgrade head`。配置模板写在 `deploy/k8s/10-paper-doc-mcp.yaml` 末尾的注释里,解开注释即可。 - **前端 SPA**:需要额外构建(pnpm build)+ nginx 镜像,目前没做。 ## 文件清单 ``` deploy/ ├── build-mcp-image.sh # DinD 构建并推送镜像 ├── README.md # 本文件 └── k8s/ ├── 00-namespace.yaml ├── 10-paper-doc-mcp.yaml # ConfigMap + Deployment + Service(含 API 的注释模板) └── secret.example.yaml # Secret 模板,真值不入库 ```