Files
paper-doc/deploy/README.md
T
govin ebaf9e558b backend: let a model put a figure in the paper, and set a formula's alignment
Two things the editor gained and MCP could not do, both because the tool layer
had been told about the domain's columns by hand.

**A figure.** Bytes go to MinIO and the sentence keeps a Markdown address, so a
picture is ordinary text — which means the writing tools already carry it, and
the only half a model cannot do is the upload: it has bytes and no way to send
multipart. `image_upload` takes base64 and answers with the URL, the Markdown
and the *sentence object* the editor produces when a picture is dropped in, so a
figure is written by putting that object into `sentences` unchanged. It does not
fetch a URL the caller names: a service inside the cluster that will GET any
address it is handed is an SSRF primitive aimed at everything beside it.

The width argument is the reader's rule or it is refused. `{width=70%}` is
parsed by `frontend/src/utils/rich.ts`, and a value it cannot read is not an
error there — the picture just prints at its natural size. A size that silently
does not apply is worse than a refusal, so the syntax and the range (pixels
1–4000, per cent 1–100) are mirrored in `app/mcp/tools/images.py`, with the
usual comment naming the other side.

`paragraph_text` also had to learn what a figure is: a sentence holding nothing
but an image is a 插图 — the view prints it on its own line with the brackets'
text as its caption — and the text a tool hands back broke lines around a
display formula but not around a picture. Same rule as `figureOf`, same pair of
implementations, same warning about changing both.

**A formula's alignment.** `paper_sentence.formula_align` reached the editor and
the REST API and stopped there: `SentenceSpec` had no such field, so a model that
sent one got a successful call and a centred formula. The column is now declared,
carried through every write path and reported by every read path.

That is the second column lost the same way, so the fix is structural rather
than another two edits. `SENTENCE_FIELDS` is read from
`app.schemas.paper.SentenceInput` instead of written out, the payload is built
by one `sentence_payload()`, and the three append paths spread
`SentenceCreate(**item.model_dump())` rather than copying fields. One edit
remains — declaring the field in `specs.py` — and smoke_mcp.py's first step
compares the two field sets, so forgetting it now fails the suite instead of
losing the field. `sort` is declared too, which it never was: a model that sent
one had it dropped in silence.

smoke_mcp.py: 99 checks to 119. The figure step uploads a real 1x1 GIF (the same
bytes twice, and the key is the same object), writes the returned sentence as it
came back, checks the paragraph prints it alone on its line and that an image
inside a sentence does not break the line, and takes the four refusals — not a
picture, an unparseable size, an out-of-range one, not base64. The alignment step
writes a right-aligned formula, moves the sentence to left on its own, and takes
the paragraph to another position to prove the setting travels with it.

Deployed as v6, and the pod now carries MINIO_ENDPOINT (the in-cluster Service)
plus the two credential keys from the Secret; without them the image tool answers
with the missing variable names and every writing tool still works.
2026-09-24 10:54:27 +08:00

153 lines
6.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 部署到 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:v6`
(`sha256:c89c0ba250c872dec45e6e5ce056dcf1f73c5415f55aa8b05216ce785ae28732`;
`kubectl -n paper-doc get pods -o jsonpath='{.items[0].status.containerStatuses[0].imageID}'`
对得上,才说明跑的就是 ACR 上那一版。历史:v1 首发布 → v2 重命名表 → v3 参考文献库 →
v4 补参考文献 MCP 工具 → v5 换行与参考文献表 → **v6 插图与公式对齐**。)
**数据库**: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 模板,真值不入库
```