Files

root 4770b3b990 refactor: Web 服务内嵌主进程 + 文档移到 docs/ 二级目录

1. Web 服务改为 threading 模式：
   - 新增 run_web_server(port) / stop_web_server() 函数
   - TUI 通过 from web_api import run_web_server 直接调用
   - 使用 werkzeug make_server 实现线程内优雅启动/停止
2. 构建脚本精简为单二进制：
   - 移除 trulymem-web 独立打包步骤
   - 添加 werkzeug 到 hidden-imports
3. 详细启动文档移到 docs/zh/quick_start.md
4. README 精简为概述，指向 docs/ 目录

2026-04-28 10:50:24 +08:00

4.8 KiB

Raw Blame History

TrulyMEM 启动指南

版本: 多用户版 (v2) — 支持 TUI 登录、多用户隔离、Web 服务内嵌

运行方式

快速启动（推荐）

# 从源码
python trulymem_entry.py

# 或打包后
./dist/TrulyMEM

首次使用 —— 登录流程

首次启动会自动检查是否需要迁移旧数据，然后进入登录页面：

新部署 → 直接输入用户名和密码创建账户（首个用户自动成为管理员）
旧版升级 → 自动检测 ~/.trulymem/config.json，引导设置用户名密码，迁移数据
已有账户 → 直接登录进入聊天界面

💡 所有用户数据隔离存储：~/.trulymem/{用户名}/

聊天配置

登录后按 F2 展开右侧配置面板：

API Key — 必须（支持 DeepSeek、OpenAI 等）
模型 — 可选，默认已配置
Base URL — 可选

配置自动保存，下次启动自动加载。

Web 可视化界面

TrulyMEM 的 Web 服务现在内嵌在主进程中（无需独立启动子进程）。

TUI 内启动（管理员专有）

管理员按 F2 打开右侧面板，勾选「启用 Web 服务」即可。

手动启动

python web_api.py --port 4096
# 访问 http://localhost:4096

首次访问流程

浏览器打开 http://localhost:4096
无用户 → 自动跳转至设置页，创建管理员账号
有用户 → 跳转至登录页
登录后进入星图可视化页面

Web 功能

页面	访问权限	功能
🌟 星图	所有已登录用户	浏览知识图谱三元组
⚙ 设置	所有已登录用户	修改密码
🧑‍💼 用户管理	仅管理员	添加/删除用户

多用户系统

目录结构

~/.trulymem/
├── trulymem.db          # 全局用户数据库（web_users 表）
├── .migrated            # 旧版迁移标记
├── admin/
│   ├── config.json      # 管理员配置
│   └── admin_graph.db   # 管理员知识图谱
└── user2/
    ├── config.json      # user2 配置
    └── user2_graph.db   # user2 知识图谱

角色体系

功能	普通用户	管理员
修改自己密码	✅	✅
配置 API Key / 模型	✅	✅
Web 服务开关（TUI）	❌	✅
Web 登录凭据	❌	✅
查看用户列表	❌	✅
添加/删除用户	❌	✅

⚠️ 首个注册用户自动成为管理员。Web 设置页可添加新用户。

快捷键

按键	功能
F1	帮助
F2	切换侧边栏（配置面板）
F3	工具详情
F5	清屏
F6	退出

打包构建

# Linux
bash build/build_linux.sh

# macOS
bash build/build_macos.sh

# Windows
build\build_windows.bat

# AppImage
bash build/build_appimage.sh

构建产出：dist/TrulyMEM（单文件，TUI + Web 服务均内嵌于同一二进制）

📦 从 v2 开始，Web 服务作为线程嵌入主程序，不再需要独立打包 trulymem-web。

架构说明

通信协议

UI 与后端通过 Packet 协议 通信：

TUI (Textual)  ←→  BackendClient  ←→  queue.Queue  ←→  BackendServer (独立线程)

配置管理

用户级存储: ~/.trulymem/{username}/config.json
Web 配置: ~/.trulymem/trulymem.db（web_users 表）
自动加载: 启动时根据登录用户加载对应配置文件
动态更新: 运行时修改配置立即生效，自动持久化

Web 服务架构

┌──────────────────────┐
│    TrulyMEM 主进程    │
│  ┌──────┐ ┌────────┐ │
│  │ TUI  │ │ Flask  │ │  ← 同一进程，不同线程
│  │      │ │ Thread │ │
│  └──────┘ └────────┘ │
└──────────────────────┘

常见问题

Python 未找到

安装 Python 3.8+：https://www.python.org/downloads/

依赖安装失败

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
pip install -r requirements.txt

API Key 无效

检查 API Key 格式，确保无多余空格。可在 TUI 右侧面板重新配置。

管理员账号丢失

数据库中第一个注册账号总是 admin。如果所有用户都丢失了 admin 权限，删除用户目录下的 trulymem.db 后重新注册即可。

旧版数据迁移

检测到旧版 ~/.trulymem/config.json 和 graph_memory.db 时，TUI 启动时自动进入迁移引导。迁移后旧文件保留，不会删除。

开发命令

pip install -r requirements.txt
pytest tests/
bash build/build_linux.sh

4.8 KiB Raw Blame History Unescape Escape