deployment.md 7.4 KB
服务器部署
Linux 首次部署
准备项目代码（包含 pyproject.toml、uv.lock、.python-version、src、scripts、html、deploy.sh）、可读取的 metadata 模板及 relation.xlsx；确认 Neo4j、Redis、DMS 和 DeepSeek 可用。
# 首次创建；已有 .env 时跳过，避免覆盖
[ -f .env ] || cp .env.example .env
# 编辑 .env 中的真实连接配置、监听地址、模板及模型目录
sh deploy.sh templates
该命令完成 uv 安装（缺失时）、Python 安装、锁定依赖同步、模型下载/验证、模板与数据更新、版本发布、服务启动。uv 自动安装到项目 .runtime/bin，不改 shell 配置；已有 PATH 或 ~/.local/bin 中的 uv 优先使用。
环境安装依据 uv 官方安装说明 和 Python 管理说明。项目依赖按 uv.lock 同步，不重新生成锁文件。
从旧版 Python 3.11 部署升级
更新代码时一并上传 .python-version，然后重新执行 sh deploy.sh templates。脚本会通过 uv 安装 Python 3.14.5 并同步项目虚拟环境；不需要修改系统 Python。若服务器曾设置 DEPLOY_PYTHON=3.11，先执行 unset DEPLOY_PYTHON，或显式运行 DEPLOY_PYTHON=3.14.5 sh deploy.sh templates。已有服务应先停止再执行模板更新。
SyntaxError: f-string expression part cannot include a backslash 来自旧代码在 f-string 表达式内转义 Markdown 竖线，该写法不兼容 Python 3.11。现已将转义移到表达式外，保持报告内容不变。
操作选择
| 命令 | 作用 |
|---|---|
sh deploy.sh setup |
只准备环境和模型，不操作业务数据或启动服务 |
sh deploy.sh model |
确保环境和模型就绪；完整模型不重复下载 |
sh deploy.sh templates |
准备环境和模型 → 模板更新 → 自动启动 |
sh deploy.sh dms |
准备环境和模型 → 数据更新 → 自动启动，要求已有模板基线 |
sh deploy.sh start |
准备环境和模型 → 启动已发布版本 |
sh deploy.sh restart |
准备完成后优雅停止本项目受管服务，加载新代码启动；不更新业务数据 |
不传参数默认执行 templates。可追加 --host 0.0.0.0 --port 8000 覆盖监听配置（setup/model 不接受监听参数）。服务前台运行，Ctrl+C 停止；没有后台 PID 管理、自动杀进程或开机自启。替换代码后使用 sh deploy.sh restart；templates/dms 更新前仍需先停止旧实例。
.env 配置示例
SERVICE_HOST=0.0.0.0
SERVICE_PORT=8000
METADATA_TEMPLATE_DIR=/srv/knowledge-data/metadata
RELATION_DIR=/srv/knowledge-data/relations
EMBEDDING_MODEL_DIR=/srv/knowledge-data/models/Qwen3-Embedding-0.6B
EMBEDDING_MODEL_REPO=Qwen/Qwen3-Embedding-0.6B
EMBEDDING_MODEL_SOURCE=modelscope
还需填写 .env.example 中列出的数据库、Redis、DMS 和模型服务凭据。目录相对值以项目根为基准；进程环境优先于 .env。模板目录必须存在且可读；关系文件固定为 RELATION_DIR/relation.xlsx。模型目录允许自动创建，运行账号需有写入权限。下载和 Step2/Step3 编码器共用 EMBEDDING_MODEL_DIR，运行编码器仅加载本地文件。
下载与安装控制
默认下载 Qwen 官方 ModelScope 模型。ModelScope 下载依赖由 uv 的临时环境提供，不加入项目锁文件。设置 EMBEDDING_MODEL_SOURCE=huggingface 可改用 Hugging Face；两个来源使用各自的 EMBEDDING_MODEL_REPO 仓库标识，切换其他模型时请使用新的模型目录，避免复用旧权重。
模型检查包含配置、分片文件和本地实际加载/编码。中断下载可重新执行；已完整且可加载时不会联网下载。只检查本地文件：
uv run --frozen python scripts/download_model.py --check-only
# 文件损坏时重新调用下载器修复；保留现有目录，不执行删除
uv run --frozen python scripts/download_model.py --force
以下变量在 shell 中设置（不从 .env 读取），示例：
AUTO_INSTALL_UV=0 DEPLOY_PYTHON=3.14.5 sh deploy.sh setup
UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple sh deploy.sh setup
AUTO_INSTALL_UV 默认 1；设为 0 时缺 uv 会报错。DEPLOY_PYTHON 未设置时读取项目 .python-version（3.14.5），与本地开发版本保持一致；安装、同步和各运行步骤均显式使用选定版本。UV_CACHE_DIR 默认项目 .uv-cache。uv 自身安装需 curl 或 wget 以及到官方安装地址的网络；Python、依赖和模型下载需对应网络访问与磁盘空间。脚本不会执行 .env 中的 shell 表达式。
Windows
本地测试直接在 PowerShell 中执行，无需 Git Bash：
uv sync --frozen
if ($LASTEXITCODE -ne 0) { throw "环境安装失败" }
uv run --frozen python scripts/download_model.py
if ($LASTEXITCODE -ne 0) { throw "模型准备失败" }
uv run --frozen python scripts/update_data.py --mode templates
if ($LASTEXITCODE -ne 0) { throw "模板更新失败" }
uv run --frozen python scripts/start_service.py
日常数据更新将 --mode templates 改为 --mode dms；仅启动直接执行最后一行，代码替换后重启添加 --restart。README 的 Windows 本地测试 提供分别可复制的操作块。更新前先停止旧服务，命令沿用 .env 中的路径及监听配置。
Windows 中路径可写为 D:/knowledge-data/...，现有模型可复用；不要把 Windows 的 .venv 复制到 Linux。Linux 部署继续使用 deploy.sh。
失败恢复与验证边界
环境或模型准备失败时，不运行更新或服务；缺 .env 时创建示例并提示填写，不直接以示例配置更新。更新失败不会启动；更新成功但启动失败，已发布版本保留，修复端口/连接问题后执行 start 即可。端口被占用时先确认并停止旧实例。
启动脚本会打印浏览器访问地址。服务在 0.0.0.0 监听时，本机访问 http://127.0.0.1:端口/，同事访问启动时打印的局域网地址；0.0.0.0 本身不能用于浏览器访问。局域网 IP 可能随 DHCP 变化，同事连接同一局域网并确保防火墙放行相应端口。
已完成离线编排测试及当前 Windows 本地模型加载/编码验证；Linux 新机安装、联网模型下载及真实业务部署需在目标服务器验收。
替换代码后重启
sh deploy.sh restart
# 也可覆盖新实例的监听参数
sh deploy.sh restart --host 0.0.0.0 --port 8000
先完成环境、配置及模型检查，再请求旧服务优雅退出，最多等待30秒；退出后启动新实例，不执行模板或数据更新。没有受管服务时直接启动。重复start会拒绝启动第二个受管实例。
服务持有 .runtime/service.lock，通过 .runtime/service-control.json 中的随机凭据连接本机控制通道；仅请求本项目服务退出，不按端口杀进程。超时或身份确认失败会报错，不强制结束进程或启动新实例。正常退出会清理控制信息。
首次升级到此版本时，已运行的旧服务没有管理记录，需要在原终端按 Ctrl+C 停止一次；之后通过此入口启动的服务均可restart。若其他程序占用端口，仍需手动处理。服务继续前台运行；新实例启动失败时旧服务不会自动恢复。