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