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
parent aefaea7b90
commit 4770b3b990
11 changed files with 526 additions and 777 deletions
--- a/docs/en/quick_start.md
+++ b/docs/en/quick_start.md
@ -1,123 +1,176 @@
 # TrulyMEM Quick Start Guide

-## Running Methods
+> **Version**: Multi-user (v2) — TUI login, user isolation, embedded Web server

-### Run from Source
+---
+
+## Running
+
+### Quick Start

 ```bash
-git clone <repo-url>
-cd TrulyMEM-TrueHumanMEM
-
-pip install -r requirements.txt
-
+# From source
 python trulymem_entry.py
+
+# Packaged binary
+./dist/TrulyMEM
 ```

-### Run After Build
+### First Run — Login Flow

-After building, an executable will be generated:
+On first launch, TrulyMEM checks for legacy data and presents a **login screen**:
+
+1. **Clean install** → Enter username/password (first user becomes admin)
+2. **Legacy upgrade** → Detects `~/.trulymem/config.json`, guides migration setup
+3. **Returning user** → Login directly
+
+> 💡 All user data is isolated: `~/.trulymem/{username}/`
+
+### Chat Configuration
+
+After login, press **F2** to open the right-side configuration panel:
+
+1. **API Key** — Required (DeepSeek, OpenAI, etc.)
+2. **Model** — Optional
+3. **Base URL** — Optional
+
+Config saves automatically.
+
+---
+
+## Web Visualization
+
+The Web service now runs **embedded in the main process** (no separate subprocess needed).
+
+### Start via TUI (Admin only)
+
+Admin users: press F2 → check "Enable Web Service".
+
+### Start Manually

 ```bash
-# Linux/macOS
-chmod +x TrulyMEM
-./TrulyMEM
-
-# Windows
-TrulyMEM.exe
-```
-
-## System Requirements
-
- **Python 3.8+**
- **API Key** (DeepSeek, OpenAI, or other compatible APIs)
-
-## First-Time Configuration
-
-1. Run the application
-2. Press **F2** to expand sidebar
-3. Enter **API Key**, **Model**, **Base URL**
-4. Press **Enter** to save
-
-Config will be automatically saved to `~/.trulymem/config.json` and loaded on next startup.
-
-### Web Visualization (Optional)
-
-TrulyMEM provides a Web star-map visualization interface for browsing the knowledge graph in real-time:
-
-```bash
-# Start Web service
 python web_api.py --port 4096
+# Visit http://localhost:4096
 ```

-Then open `http://localhost:4096` in your browser.
+### First Visit Flow

-**Login Setup:**
-1. Copy `web_config.example.json` to `web_config.json`
-2. Set login password (using SHA256) and secret key
-3. Web service will automatically read the config
+1. Open `http://localhost:4096` in browser
+2. **No users** → Auto-redirect to setup page, create admin account
+3. **Has users** → Login page
+4. After login → Star map visualization

-Default port is 4096, change with `--port` flag.
+### Web Features
+
+| Page | Access | Feature |
+|------|--------|---------|
+| 🌟 Star Map | All logged-in | Browse knowledge graph |
+| ⚙ Settings | All logged-in | Change password |
+| 🧑‍💼 User Management | **Admin only** | Add/delete users |
+
+---
+
+## Multi-User System
+
+### Directory Layout
+
+```
+~/.trulymem/
+├── trulymem.db          # Global user database (web_users table)
+├── .migrated            # Migration flag
+├── admin/
+│   ├── config.json      # Admin config
+│   └── admin_graph.db   # Admin knowledge graph
+└── user2/
+    ├── config.json      # user2 config
+    └── user2_graph.db   # user2 knowledge graph
+```
+
+### Role Matrix
+
+| Feature | User | Admin |
+|---------|------|-------|
+| Change password | ✅ | ✅ |
+| Configure API Key / Model | ✅ | ✅ |
+| Web service toggle (TUI) | ❌ | ✅ |
+| Web login credentials | ❌ | ✅ |
+| View user list | ❌ | ✅ |
+| Add/delete users | ❌ | ✅ |
+
+> ⚠️ First registered user becomes admin automatically. Add users via Web settings page.

 ---

 ## Keyboard Shortcuts

-| Key | Function |
-|-----|-----------|
+| Key | Action |
+|-----|--------|
 | F1 | Help |
-| F2 | Toggle sidebar |
+| F2 | Toggle sidebar (config panel) |
 | F3 | Tool details |
 | F5 | Clear screen |
-| F6 | Exit |
+| F6 | Quit |

-## Data Storage
+---

-### Source Mode
+## Building

-| Data | Location |
-|------|----------|
-| Graph database | Project directory `graph_memory.db` |
-| Config file | Project directory `config.json` (if exists) |
-| Database format | SQLite |
+```bash
+# Linux
+bash build/build_linux.sh

-### Packaged Mode
+# macOS
+bash build/build_macos.sh

-| Data | Location |
-|------|----------|
-| Graph database | `~/.trulymem/graph_memory.db` |
-| Config file | `~/.trulymem/config.json` |
-| Database format | SQLite |
+# Windows
+build\build_windows.bat

-> **Note**: Backend manages config uniformly. Frontend only displays messages; config modifications are persisted to filesystem through the backend.
+# AppImage
+bash build/build_appimage.sh
+```

-## Architecture Explanation
+Output: `dist/TrulyMEM` (single binary — TUI and Web server embedded)

-### Communication Protocol
+> 📦 Since v2, the Web server runs as a thread inside the main process. No need for a separate `trulymem-web` binary.

-UI and backend communicate via **Packet Protocol**:
+---
+
+## Architecture
+
+### Communication

 ```
-UI (Textual TUI)
-    ↓ BackendClient
-Packet → queue.Queue → BackendServer (independent thread)
-    ↓
-Process request → Return response
+TUI (Textual)  ←→  BackendClient  ←→  queue.Queue  ←→  BackendServer (thread)
 ```

 ### Config Management

- **Storage location**: `~/.trulymem/config.json`
- **Auto-load**: Load config from file at startup
- **Dynamic update**: Config changes take effect immediately at runtime
- **Persistence**: Auto-save to file after modification
+- **Per-user**: `~/.trulymem/{username}/config.json`
+- **Web config**: `~/.trulymem/trulymem.db` (web_users table)
+- **Auto-load**: reads config for logged-in user on startup
+- **Persistent**: saves automatically on change

-## Common Issues
+### Web Service Architecture

-### Python Not Found
+```
+┌──────────────────────┐
+│   TrulyMEM Process   │
+│  ┌──────┐ ┌────────┐ │
+│  │ TUI  │ │ Flask  │ │  ← Same process, different threads
+│  │      │ │ Thread │ │
+│  └──────┘ └────────┘ │
+└──────────────────────┘
+```
+
+---
+
+## FAQ
+
+### Python not found

 Install Python 3.8+: https://www.python.org/downloads/

-### Dependency Installation Failed
+### Dependency installation fails

 ```bash
 python -m venv venv
@ -128,18 +181,22 @@ pip install -r requirements.txt

 ### Invalid API Key

-Check API Key format, ensure no extra spaces.
+Check format and whitespace. Reconfigure in TUI sidebar.

-## Development Commands
+### Lost admin account
+
+The first registered user is always admin. If all users lost admin, delete `trulymem.db` from the user directory and re-register.
+
+### Legacy data migration
+
+When old `~/.trulymem/config.json` and `graph_memory.db` are detected, TUI auto-enters migration flow. Legacy files are preserved.
+
+---
+
+## Dev Commands

 ```bash
-# Install dependencies
 pip install -r requirements.txt
-
-# Run tests
 pytest tests/
-
-# Build
-bash build/build_windows.bat   # Windows
-bash build/build_linux.sh       # Linux
-```
+bash build/build_linux.sh
+```
--- a/docs/zh/quick_start.md
+++ b/docs/zh/quick_start.md
@ -1,62 +1,103 @@
 # TrulyMEM 启动指南

+> **版本**: 多用户版 (v2) — 支持 TUI 登录、多用户隔离、Web 服务内嵌
+
+---
+
 ## 运行方式

-### 从源码运行
+### 快速启动（推荐）

 ```bash
-git clone <repo-url>
-cd TrulyMEM-TrueHumanMEM
-
-pip install -r requirements.txt
-
+# 从源码
 python trulymem_entry.py
+
+# 或打包后
+./dist/TrulyMEM
 ```

-### 打包后运行
+### 首次使用 —— 登录流程

-打包后会生成可执行文件：
+首次启动会自动检查是否需要迁移旧数据，然后进入**登录页面**：
+
+1. **新部署** → 直接输入用户名和密码创建账户（首个用户自动成为管理员）
+2. **旧版升级** → 自动检测 `~/.trulymem/config.json`，引导设置用户名密码，迁移数据
+3. **已有账户** → 直接登录进入聊天界面
+
+> 💡 所有用户数据隔离存储：`~/.trulymem/{用户名}/`
+
+### 聊天配置
+
+登录后按 **F2** 展开右侧配置面板：
+
+1. **API Key** — 必须（支持 DeepSeek、OpenAI 等）
+2. **模型** — 可选，默认已配置
+3. **Base URL** — 可选
+
+配置自动保存，下次启动自动加载。
+
+---
+
+## Web 可视化界面
+
+TrulyMEM 的 Web 服务现在**内嵌在主进程中**（无需独立启动子进程）。
+
+### TUI 内启动（管理员专有）
+
+管理员按 F2 打开右侧面板，勾选「启用 Web 服务」即可。
+
+### 手动启动

 ```bash
-# Linux/macOS
-chmod +x TrulyMEM
-./TrulyMEM
-
-# Windows
-TrulyMEM.exe
-```
-
-## 系统要求
-
- **Python 3.8+**
- **API Key**（DeepSeek、OpenAI 或其他兼容 API）
-
-## 首次配置
-
-1. 运行应用
-2. 按 **F2** 展开侧边栏
-3. 输入 **API Key**、**模型**、**Base URL**
-4. 按 **Enter** 保存
-
-配置会自动保存到 `~/.trulymem/config.json`，下次启动自动加载。
-
-### Web 可视化界面（可选）
-
-TrulyMEM 提供 Web 星图可视化界面，支持实时浏览知识图谱：
-
-```bash
-# 启动 Web 服务
 python web_api.py --port 4096
+# 访问 http://localhost:4096
 ```

-然后打开浏览器访问 `http://localhost:4096`。
+### 首次访问流程

-**登录配置：**
-1. 复制 `web_config.example.json` 为 `web_config.json`
-2. 设置登录密码（使用 SHA256）和 secret key
-3. Web 服务会自动读取该配置
+1. 浏览器打开 `http://localhost:4096`
+2. **无用户** → 自动跳转至设置页，创建管理员账号
+3. **有用户** → 跳转至登录页
+4. 登录后进入星图可视化页面

-默认端口 4096，可通过 `--port` 参数修改。
+### 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 设置页可添加新用户。

 ---

@ -65,30 +106,34 @@ python web_api.py --port 4096
 | 按键 | 功能 |
 |------|------|
 | F1 | 帮助 |
-| F2 | 切换侧边栏 |
+| F2 | 切换侧边栏（配置面板） |
 | F3 | 工具详情 |
 | F5 | 清屏 |
 | F6 | 退出 |

-## 数据存储
+---

-### 源码运行模式
+## 打包构建

-| 数据 | 位置 |
-|------|------|
-| 图数据库 | 项目目录 `graph_memory.db` |
-| 配置文件 | 项目目录 `config.json`（如存在） |
-| 数据库格式 | SQLite |
+```bash
+# Linux
+bash build/build_linux.sh

-### 打包运行模式
+# macOS
+bash build/build_macos.sh

-| 数据 | 位置 |
-|------|------|
-| 图数据库 | `~/.trulymem/graph_memory.db` |
-| 配置文件 | `~/.trulymem/config.json` |
-| 数据库格式 | SQLite |
+# Windows
+build\build_windows.bat

-> **说明**：后端统一管理配置。前端仅负责消息展示，配置修改通过后端持久化到文件系统。
+# AppImage
+bash build/build_appimage.sh
+```
+
+构建产出：`dist/TrulyMEM`（单文件，TUI + Web 服务均内嵌于同一二进制）
+
+> 📦 从 v2 开始，Web 服务作为线程嵌入主程序，不再需要独立打包 `trulymem-web`。
+
+---

 ## 架构说明

@ -97,19 +142,29 @@ python web_api.py --port 4096
 UI 与后端通过 **Packet 协议** 通信：

 ```
-UI (Textual TUI)
-    ↓ BackendClient
-Packet → queue.Queue → BackendServer (独立线程)
-    ↓
-处理请求 → 返回响应
+TUI (Textual)  ←→  BackendClient  ←→  queue.Queue  ←→  BackendServer (独立线程)
 ```

 ### 配置管理

- **存储位置**: `~/.trulymem/config.json`
- **自动加载**: 启动时从文件读取配置
- **动态更新**: 运行时修改配置立即生效
- **持久化**: 修改后自动保存到文件
+- **用户级存储**: `~/.trulymem/{username}/config.json`
+- **Web 配置**: `~/.trulymem/trulymem.db`（web_users 表）
+- **自动加载**: 启动时根据登录用户加载对应配置文件
+- **动态更新**: 运行时修改配置立即生效，自动持久化
+
+### Web 服务架构
+
+```
+┌──────────────────────┐
+│    TrulyMEM 主进程    │
+│  ┌──────┐ ┌────────┐ │
+│  │ TUI  │ │ Flask  │ │  ← 同一进程，不同线程
+│  │      │ │ Thread │ │
+│  └──────┘ └────────┘ │
+└──────────────────────┘
+```
+
+---

 ## 常见问题

@ -128,18 +183,22 @@ pip install -r requirements.txt

 ### API Key 无效

-检查 API Key 格式，确保无多余空格。
+检查 API Key 格式，确保无多余空格。可在 TUI 右侧面板重新配置。
+
+### 管理员账号丢失
+
+数据库中第一个注册账号总是 admin。如果所有用户都丢失了 admin 权限，删除用户目录下的 `trulymem.db` 后重新注册即可。
+
+### 旧版数据迁移
+
+检测到旧版 `~/.trulymem/config.json` 和 `graph_memory.db` 时，TUI 启动时自动进入迁移引导。迁移后旧文件保留，不会删除。
+
+---

 ## 开发命令

 ```bash
-# 安装依赖
 pip install -r requirements.txt
-
-# 运行测试
 pytest tests/
-
-# 打包
-bash build/build_windows.bat   # Windows
-bash build/build_linux.sh       # Linux
-```
+bash build/build_linux.sh
+```