212 lines
4.9 KiB
Markdown
212 lines
4.9 KiB
Markdown
# 织忆 (MemoryWeave) — 手动安装指南
|
||
|
||
本文档提供非 Docker 环境下的完整安装步骤（systemd 用户级服务）。
|
||
|
||
## 前置条件
|
||
|
||
- Linux（本文以 Arch Linux 为例）
|
||
- Go 1.21+
|
||
- Redis 7.0+（可选，内存模式可跳过）
|
||
- systemd（用户级服务支持）
|
||
|
||
## Step 0：确认目录结构
|
||
|
||
```bash
|
||
mkdir -p ~/.config/systemd/user
|
||
mkdir -p ~/.local/bin
|
||
mkdir -p /var/lib/memoryweave
|
||
mkdir -p ~/.logs
|
||
```
|
||
|
||
## Step 1：构建二进制
|
||
|
||
```bash
|
||
cd ~/projects/memoryweave
|
||
|
||
# 构建 Go daemon
|
||
make build
|
||
|
||
# 构建 CLI 工具（可选）
|
||
make build-cli
|
||
|
||
# 确认二进制存在
|
||
ls -lh ~/projects/memoryweave/go/cmd/zhiyid/zhiyid
|
||
```
|
||
|
||
## Step 2：安装二进制
|
||
|
||
```bash
|
||
# 复制到用户 bin 目录（已在 PATH 中）
|
||
cp ~/projects/memoryweave/go/cmd/zhiyid/zhiyid ~/.local/bin/zhiyid
|
||
chmod +x ~/.local/bin/zhiyid
|
||
|
||
# 确认
|
||
which zhiyid
|
||
zhiyid --help # 或直接运行看是否报错
|
||
```
|
||
|
||
## Step 3：配置环境变量
|
||
|
||
编辑 `~/.config/zhiyi/config.env`（或直接使用 systemd service 中的 Environment）：
|
||
|
||
```bash
|
||
mkdir -p ~/.config/zhiyi
|
||
cat > ~/.config/zhiyi/config.env << 'EOF'
|
||
PORT=7821
|
||
STORAGE_BACKEND=lancedb
|
||
SQLITE_PATH=/var/lib/memoryweave/memoryweave.db
|
||
GRAPH_PATH=/var/lib/memoryweave/graph.db
|
||
API_KEY=your-secret-api-key-here
|
||
VLLM_ENDPOINT=http://127.0.0.1:8000/v1/embeddings
|
||
RERANK_ENDPOINT=https://ai.gitee.com/v1
|
||
LLM_ENDPOINT=http://127.0.0.1:3000/v1/chat/completions
|
||
LLM_MODEL=qwen/qwen3.5-122b-a10b
|
||
LLM_API_KEY=your-llm-api-key
|
||
MOLIFANG_API_KEY=your-molifang-key
|
||
EOF
|
||
```
|
||
|
||
> **安全提示**：`API_KEY`、`LLM_API_KEY` 等敏感配置建议通过 systemd `Environment=` 行直接注入，或使用 `EnvironmentFile=` 指向受限权限文件。
|
||
|
||
## Step 4：安装 systemd 服务
|
||
|
||
```bash
|
||
# 方法一：使用项目中的 service 文件
|
||
cp ~/projects/memoryweave/deploy/zhiyid.service ~/.config/systemd/user/zhiyid.service
|
||
|
||
# 方法二：手动创建（完整示例见下方）
|
||
cat > ~/.config/systemd/user/zhiyid.service << 'EOF'
|
||
[Unit]
|
||
Description=ZhiYi MemoryWeave (织忆) — Go Service
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
ExecStartPre=/bin/mkdir -p /var/lib/memoryweave ~/.logs
|
||
ExecStart=/home/muc/.local/bin/zhiyid
|
||
Restart=always
|
||
RestartSec=5
|
||
Environment=PORT=7821
|
||
Environment=STORAGE_BACKEND=lancedb
|
||
Environment=SQLITE_PATH=/var/lib/memoryweave/memoryweave.db
|
||
Environment=GRAPH_PATH=/var/lib/memoryweave/graph.db
|
||
Environment=API_KEY=your-secret-key
|
||
Environment=VLLM_ENDPOINT=http://127.0.0.1:8000/v1/embeddings
|
||
Environment=RERANK_ENDPOINT=https://ai.gitee.com/v1
|
||
Environment=LLM_ENDPOINT=http://127.0.0.1:3000/v1/chat/completions
|
||
Environment=LLM_MODEL=qwen/qwen3.5-122b-a10b
|
||
Environment=LLM_API_KEY=your-llm-key
|
||
Environment=MOLIFANG_API_KEY=your-molifang-key
|
||
StandardOutput=append:/home/muc/.logs/zhiyid.log
|
||
StandardError=append:/home/muc/.logs/zhiyid.log
|
||
|
||
[Install]
|
||
WantedBy=default.target
|
||
EOF
|
||
```
|
||
|
||
**编辑密钥**：将上述 `your-secret-key` 等替换为真实值。
|
||
|
||
## Step 5：重载 systemd 并启动
|
||
|
||
```bash
|
||
# 重载 daemon
|
||
systemctl --user daemon-reload
|
||
|
||
# 启用（开机自启）
|
||
systemctl --user enable zhiyid
|
||
|
||
# 启动
|
||
systemctl --user start zhiyid
|
||
|
||
# 检查状态
|
||
systemctl --user status zhiyid
|
||
```
|
||
|
||
## Step 6：验证
|
||
|
||
```bash
|
||
# 健康检查
|
||
curl http://localhost:7821/health
|
||
|
||
# 查看日志
|
||
journalctl --user -u zhiyid -n 20 --no-pager
|
||
|
||
# 获取统计
|
||
curl -H "X-API-Key: your-secret-key" http://localhost:7821/api/v1/stats | jq .
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### Q：服务启动失败
|
||
|
||
```bash
|
||
# 查看详细日志
|
||
journalctl --user -u zhiyid -xe --no-pager
|
||
```
|
||
|
||
常见原因：
|
||
- 端口 7821 被占用 → 修改 `PORT` 环境变量
|
||
- 目录不存在 → `mkdir -p /var/lib/memoryweave ~/.logs`
|
||
- 二进制无执行权限 → `chmod +x ~/.local/bin/zhiyid`
|
||
|
||
### Q：Redis 未安装
|
||
|
||
默认降级为内存存储，无需 Redis。保留 `redis-server.service` 相关行无影响。
|
||
|
||
### Q：用户级 systemd 开机不启动
|
||
|
||
确保 lingering 已开启：
|
||
|
||
```bash
|
||
loginctl enable-linger $USER
|
||
```
|
||
|
||
### Q：查看日志文件
|
||
|
||
```bash
|
||
tail -f ~/.logs/zhiyid.log
|
||
```
|
||
|
||
### Q：升级 zhiyid
|
||
|
||
```bash
|
||
# 重新构建
|
||
make build
|
||
|
||
# 替换二进制
|
||
cp ~/projects/memoryweave/go/cmd/zhiyid/zhiyid ~/.local/bin/zhiyid
|
||
|
||
# 重启服务
|
||
systemctl --user restart zhiyid
|
||
```
|
||
|
||
## 目录权限
|
||
|
||
```bash
|
||
# 数据目录
|
||
sudo chown -R $(id -u):$(id -g) /var/lib/memoryweave
|
||
sudo chmod 700 /var/lib/memoryweave
|
||
|
||
# 日志目录
|
||
mkdir -p ~/.logs
|
||
chmod 700 ~/.logs
|
||
|
||
# config
|
||
chmod 600 ~/.config/zhiyi/config.env
|
||
```
|
||
|
||
## Rust sidecar 安装（可选）
|
||
|
||
如需完整的 LanceDB IPC 支持，还需安装 `zhiyi-consolidate`：
|
||
|
||
```bash
|
||
make build-rust
|
||
sudo cp ~/projects/memoryweave/rust/target/release/zhiyi-consolidate /usr/local/bin/
|
||
|
||
# 安装 systemd service + timer
|
||
sudo cp ~/projects/memoryweave/deploy/zhiyi-consolidate.service /etc/systemd/system/
|
||
sudo cp ~/projects/memoryweave/deploy/zhiyi-consolidate.timer /etc/systemd/system/
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now zhiyi-consolidate.timer
|
||
``` |