MeetYou Core 部署运维手册

MeetYou 部署运维 Linux systemd PostgreSQL

创建于 2026-05-09

MeetYou Core 部署运维手册

Summary

这篇是 MeetYou 项目专属命令手册。它把 [03-Linux-命令笔记](03-Linux-命令笔记.html)、[04-Docker-相关知识笔记](04-Docker-相关知识笔记.html)、[05-Git-SSH-GitHub-命令笔记](05-Git-SSH-GitHub-命令笔记.html) 中的通用知识收束到一个实际目标：让 Core 在 Linux 服务器上稳定运行、可更新、可回滚、可观测。

1. 当前推荐形态

云服务器 Ubuntu
  -> PostgreSQL
  -> MeetYou Core: Python venv + service_runtime
  -> systemd 常驻
  -> Nginx/Caddy 反向代理 HTTPS/WSS
  -> Windows Desktop / Edge / Feishu / WeChatBot 等 endpoint 接入

Note

当前阶段优先用 venv + systemd 跑 Core，Docker 更适合 sidecar、桥接服务、代理、采集器等外围模块。未来 Core 稳定后再容器化也可以。

2. 项目架构口径

V4 方向的核心原则：

Core owns Runtime
Client / Desktop / Edge 只是 Endpoint Provider
Tool 调度通过 ToolRouter + ExecutionTarget
Delivery 负责投递 Message / RunEvent / Notice
Scheduler 是系统唯一调度时钟
system.heartbeat 是 Scheduler 中的系统预设任务

这意味着运维上要重点关心：

Core 是否健康。
Endpoint 是否连接。
RunEvent/Delivery 是否可恢复。
ToolRouter/ExecutionTarget 是否能正确路由。
Scheduler/Heartbeat 是否正常。

3. 服务器基础准备

推荐服务器：

Ubuntu Server 24.04 LTS 或 22.04 LTS
2 核 4G 起步
公网 IP
安全组开放 22、80、443
数据库端口不要公开暴露

基础包：

sudo apt update
sudo apt install -y git curl nano python3 python3-venv postgresql postgresql-contrib

4. PostgreSQL 初始化

sudo apt install -y postgresql postgresql-contrib
sudo systemctl status postgresql

进入：

sudo -u postgres psql

创建：

CREATE USER meetyou WITH PASSWORD '改成强密码';
CREATE DATABASE meetyou OWNER meetyou;
GRANT ALL PRIVILEGES ON DATABASE meetyou TO meetyou;
\q

测试：

psql -h 127.0.0.1 -U meetyou -d meetyou

5. 拉取项目与虚拟环境

cd /opt
sudo mkdir -p /opt/meetyou
sudo chown ubuntu:ubuntu /opt/meetyou
cd /opt/meetyou
git clone git@github.com:yourname/MeetYou.git
cd /opt/meetyou/MeetYou
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements-core.txt

Tip

私有仓库建议用 SSH key 拉取。先用 `ssh -T git@github.com` 测通，再 clone。

6. 配置文件

复制模板：

cp .env.example .env
cp user/config.example.json user/config.json
cp user/tools.example.json user/tools.json
cp user/cmd_policy.example.json user/cmd_policy.json
cp user/source_catalog.example.json user/source_catalog.json
cp user/memory_graph.example.json user/memory_graph.json

生成 token：

openssl rand -hex 32
openssl rand -hex 32

.env 最小关键项：

MEETYOU_API_KEY=<你的大模型 API Key>
MEETYOU_HEARTBEAT_API_KEY=<心跳模型 API Key>
MEETYOU_EMBEDDING_API_KEY=<向量模型 API Key>
MEETYOU_GATEWAY_ACCESS_TOKEN=<随机 token>
MEETYOU_AGENT_ACCESS_TOKEN=<随机 token>
MEETYOU_DATABASE_URL=postgresql+psycopg://meetyou:<数据库密码>@127.0.0.1:5432/meetyou

校验 JSON：

python3 -m json.tool user/config.json > /tmp/config_check.json && echo OK

Danger

`.env`、API Key、数据库密码、token 不要提交到 GitHub，不要贴到公开聊天，不要写进普通同步笔记。可以单独放到加密密码管理器。

7. 手动启动验证

cd /opt/meetyou/MeetYou
source .venv/bin/activate
python -m service_runtime

另开一个 SSH 窗口测试：

curl http://127.0.0.1:8000/health

如果看到类似：

{"status":"ok"}

说明基础服务可用。

8. systemd 常驻

安装模板脚本：

sudo bash scripts/linux/install-core-systemd.sh

编辑环境：

sudo nano /etc/meetyou/meetyou-core.env

启用并启动：

sudo systemctl enable --now meetyou-core.service
sudo systemctl status meetyou-core.service --no-pager

日志：

sudo journalctl -u meetyou-core.service -n 100 --no-pager
sudo journalctl -u meetyou-core.service -f

9. Nginx/Caddy 反向代理思路

目标：

外部 https://core.maziteng.cn
  -> 443
  -> Nginx/Caddy
  -> 127.0.0.1:8000

好处：

Core 只监听本地更安全。
TLS/HTTPS/WSS 由反向代理处理。
后续可以挂多个服务和子域名。

Note

域名建议用子域名，例如 `core.maziteng.cn`，不要直接把根域名当 Core 入口。

10. 安全更新流程

ssh ubuntu@core.maziteng.cn
cd /opt/meetyou/MeetYou

git fetch origin
git pull --ff-only

source .venv/bin/activate
python -m pip install -r requirements-core.txt

sudo systemctl restart meetyou-core
sudo systemctl status meetyou-core --no-pager

健康检查：

TOKEN=$(sudo grep '^MEETYOU_GATEWAY_ACCESS_TOKEN=' /etc/meetyou/meetyou-core.env | cut -d= -f2-)
curl -H "Authorization: Bearer $TOKEN" https://core.maziteng.cn/health

11. 判断是否需要更新服务器

本地：

git diff --name-only 旧提交..新提交

服务器：

cd /opt/meetyou/MeetYou
git fetch origin
git log --oneline HEAD..origin/main -- core gateway service_runtime adapters alembic deploy/systemd requirements-core.txt

只改这些通常是 Windows 端更新，不一定要动 Core：

meetyou-ui/
desktop_agent/
user/desktop_agent.example.json

改这些通常要更新 Core：

core/
gateway/
service_runtime/
adapters/
alembic/
deploy/systemd/
requirements-core.txt

12. Windows Desktop / local bridge 检查

当前桌面侧常见结构：

Electron UI
  -> http://127.0.0.1:38951
  -> desktop local bridge
  -> remote Core: https://core.maziteng.cn

Windows 检查：

Get-NetTCPConnection -LocalPort 38951 -ErrorAction SilentlyContinue
Invoke-RestMethod http://127.0.0.1:38951/desktop/bridge/status

配置应重点看：

{
  "core_base_url": "https://core.maziteng.cn",
  "local_bridge_enabled": true,
  "local_bridge_port": 38951
}

13. 真实测试 checklist

基础测试：

[ ] python -m pytest
[ ] 前端 typecheck/build/test
[ ] migration tests
[ ] endpoint protocol tests
[ ] scheduler tests
[ ] tool router tests
[ ] delivery tests

本地真实测试：

[ ] 本地 Core + Desktop + UI 能对话
[ ] Streaming 正常
[ ] assistant.progress_notice 正常
[ ] ToolRouter 能路由本地工具
[ ] Scheduler 和 system.heartbeat 正常
[ ] 断线重连后 Thread 可继续

远程真实测试：

[ ] GitHub Actions CI 通过
[ ] Deploy 通过
[ ] 远程 Core /health 正常
[ ] 本地 Desktop 连远程 Core 正常
[ ] Feishu / WeChatBot 最后做真实收发确认

14. 运维排错顺序

遇到问题时按这个顺序，不要乱猜：

1. 服务状态：systemctl status meetyou-core
2. 日志：journalctl -u meetyou-core -n 200
3. 端口：ss -lntp | grep 8000
4. 本机健康：curl http://127.0.0.1:8000/health
5. 外部健康：curl https://core.maziteng.cn/health
6. 配置：/etc/meetyou/meetyou-core.env 与 user/config.json
7. 数据库：psql -h 127.0.0.1 -U meetyou -d meetyou
8. Git 版本：git log --oneline -n 3

15. 常用一键片段

15.1 查看最近日志

sudo journalctl -u meetyou-core -n 200 --no-pager

15.2 重启并跟日志

sudo systemctl restart meetyou-core && sudo journalctl -u meetyou-core -f

15.3 查看当前代码版本

cd /opt/meetyou/MeetYou
git log --oneline -n 5

15.4 检查 env 是否有关键项

sudo grep -E 'MEETYOU_(DATABASE_URL|GATEWAY_ACCESS_TOKEN|AGENT_ACCESS_TOKEN)=' /etc/meetyou/meetyou-core.env

不要输出 API Key 给别人。

16. 自测题

为什么 Core 生产运行要用 systemd？
更新服务器时为什么用 git pull --ff-only？
/health 本地通、外部不通，优先怀疑哪几层？
为什么 Feishu/WeChatBot 的真实测试要放最后？

我的新增记录

反向链接：00-MOC-命令行与部署知识库总览｜03-Linux-命令笔记｜05-Git-SSH-GitHub-命令笔记｜07-常见排错与小点整合