Files
paper-doc/deploy/README.md
T
govin 48f0c12fd2 frontend: let the writer set a figure's size in the editor
Figures come out of a plotting tool at whatever size they were made. On the
paper this was written for, the sixteen of them are 1441, 1857, 2409 and 4169
pixels wide — every one wider than the 1276px column — so with no size they all
printed at the full width, and the near-square ones (1857×1986, 1974×2068) took
1365px of height, a page each. Measured in the browser, all sixteen came out at
exactly 1276px: not one of them was the size its author wanted.

`{width=…}` has been in the syntax all along, so this is the control that was
missing, not the feature. A row that is a figure now carries 宽度 in its header:
25/50/70/100%, or any value typed in — the size a panel wants is what it
measures, not a round number — with 原尺寸 as the empty value. Beside it, what
the picture will measure on the page (`原图 1857×1986 · 显示 893×955`), worked
out against the column actually rendered behind the dialog, which is the number
the writer is deciding with.

Two rules keep it honest. The value goes through `parseImageWidth` — the same
function that parses the attribute when the paper is printed — so what the
control shows is what will be printed, and a value it cannot read is refused
with the forms that work instead of stored as a size that quietly does nothing.
And the attribute is written into the sentence content by `withImageWidth`,
which edits only the first picture: the control is offered for a figure, and a
sentence with words around its picture is not one. Reading the size back out of
the content rather than keeping a copy of it in the draft means there is one
place it can be wrong instead of two.

`check-image.mjs` grows from 15 checks to 24, driving the real control: that
only figure rows offer one, that it shows what each is set to, that typing 30%
converts to 383×239 immediately, that what was typed is what gets stored, that
the paper then prints it at 30% of the column, that clearing it goes back to the
natural 480×300, and that "宽一点" is refused while the sentence keeps its size.

The MCP side of the same rule was wrong and is fixed with it: `image_upload(width=
"60")` wrote `{width=60px}`, and the reader takes a bare number as a share of the
column — `parseImageWidth` only reads pixels when the value says `px`. A model
asking for 60% got a 60-pixel figure. v7 is deployed with the corrected reading,
and smoke_mcp.py checks it.
2026-09-24 11:25:18 +08:00

6.9 KiB
Raw Blame History

部署到 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 非敏感环境变量(数据库地址、监听配置、MinIO 端点与桶名)
Secret paper-doc-secrets DB_USER / DB_PASSWORD / MCP_HTTP_TOKEN / MINIO_ACCESS_KEY / MINIO_SECRET_KEY
Secret aliyun-acr 镜像仓库拉取凭证(从 default 复制)

镜像:registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v7 (sha256:f55a0d4e5ac790b78aaeb95a58034a28266e33282a379a2e1e8ffa10c191f611; kubectl -n paper-doc get pods -o jsonpath='{.items[0].status.containerStatuses[0].imageID}' 对得上,才说明跑的就是 ACR 上那一版。历史:v1 首发布 → v2 重命名表 → v3 参考文献库 → v4 补参考文献 MCP 工具 → v5 换行与参考文献表 → v6 插图与公式对齐 → v7 插图的宽度写法与页面一致。)

数据库:TiDB 已经在这个集群里,Deployment 用集群内的 Service tidb-tidb.tidb:4000,而不是宿主机用的 NodePort 192.168.1.88:32738。 两者是同一份数据;集群内用 Service 的好处是节点地址变了也不用改配置。

对象存储:论文里的插图放在 MinIO(命名空间 minio,同一个集群)。 集群内用它自己的 Service http://minio.minio.svc.cluster.local:9000, 宿主机上开发才用 NodePort http://192.168.1.88:30090;两边是同一个桶 paper-images, 桶会在第一次上传时自动创建。少给凭证不会让服务起不来:image_upload 会回一句 「图片存储还没有配置好(缺少 MINIO_…)」,写作类工具照常可用。

访问地址

从哪里连 地址
宿主机 / 局域网 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 模板,真值不入库