# 织忆 (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
```