48f0c12fd2
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.
153 lines
6.9 KiB
Markdown
153 lines
6.9 KiB
Markdown
# 部署到 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 里,取法:
|
||
|
||
```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='<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 客户端跑一遍:
|
||
|
||
```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 模板,真值不入库
|
||
```
|