The paper model gained two things while the MCP layer was not looking, and both were invisible from a tool call. `paper_sentence.line_break_before` — the flag a paragraph needs so a formula, a list of items or an author line can start a line of its own — was not in `SentenceSpec`, and `sentence_inputs` dropped it on the floor: a model could write the field, watch the call succeed, and get prose back. It is now part of every write path (`paragraph_write`, `paper_write`, `sentence_add`, `sentence_update`) and of every read path (`sentence_row` reports it, so a model can see the lines before moving one). Two bugs fell out of doing it properly: * `paragraph_move` rebuilt its sentences without the flag, so moving a paragraph that carried a formula turned it into prose. It also passed the *source* sorts through, which interleaved the moved sentences with the target's own — the merged paragraph read in an order neither writer wrote. Both are fixed; the tool now appends, as its own description promised. * `document_text` printed a formula run into the sentence before it. The paper view renders `$$…$$` as a block, so the seam rules are now the same in both places, with a comment on each side naming the other. `PaperDocumentRead.references` and `reference_style` — the per-work 参考文献 list the backend now assembles and formats — were reachable over REST but not over MCP: `paper_document(format="json")` returned citations and nothing to point them at, even though docs/MCP.md already described the list. The json form now carries the entries (index, reference_id, text, missing, citations) and the style name, so a model quotes the bibliography instead of assembling a second one out of the same fields. smoke_mcp.py grows from 76 checks to 99 over two new steps — the line-break step pins the display-formula rule, the marker toggle and the moving case; the bibliography step cites one work from two sentences and checks that the text, the entry and both markers agree on one number.
6.3 KiB
部署到 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 <MCP_HTTP_TOKEN>,否则返回 401。
Token 在 Secret 里,取法:
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:
export KUBECONFIG=$HOME/.kube/config
# 状态
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='<tidb-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 客户端跑一遍:
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 模板,真值不入库