Files
paper-doc/deploy
govin 9f2bbe50eb backend: let a model ask for a line break, and read the 参考文献 list back
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.
2026-09-23 11:49:39 +08:00
..

部署到 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 模板,真值不入库