Metadata-Version: 2.4
Name: aizz-server
Version: 1.0.1
Summary: Self-hosted AIZZ server for remote chat and Codex coding
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: uvicorn[standard]<1,>=0.30
Requires-Dist: httpx[http2]<1,>=0.27
Requires-Dist: anyio<5,>=3.7.1
Requires-Dist: PyJWT[crypto]<3,>=2.9
Requires-Dist: qrcode<9,>=8
Requires-Dist: PyYAML<7,>=6

# AIZZ Server

AIZZ 的自托管服务端。在自己的电脑上运行，使用 AIZZ APP 配对连接，进行聊天、Codex 编码任务、文件访问和交互式终端操作。

## 安装与启动

运行环境：macOS 或 Linux、Python 3.11+。Windows 请使用 WSL。服务端电脑需要提前安装并登录 Codex CLI，确保终端中可以使用 `codex` 命令。

建议安装到独立的 Python 虚拟环境：

```bash
python3 -m venv ~/.venvs/aizz
source ~/.venvs/aizz/bin/activate
python -m pip install --upgrade aizz-server
aizz serve
```

`aizz serve` 在前台运行，默认监听 `0.0.0.0:8000`，可供同一内网的设备连接。第一次启动自动创建 `~/.aizz/` 和缺失的配置文件，不覆盖已有配置和聊天记录。默认聊天使用本机 Codex 登录，无需另外配置聊天 API Key。

自定义监听地址和端口：

```bash
aizz serve --host 0.0.0.0 --port 8000
# 仅本机或同机反向代理访问：
aizz serve --host 127.0.0.1 --port 8000
```

如果需要先修改配置、稍后启动，可以只执行 `aizz init`。安装包本身不会自动启动服务。后续打开新终端时，先激活上述虚拟环境，再使用 `aizz` 命令。

## APP 配对连接

保持服务端运行，在同一台电脑的另一个终端激活虚拟环境，生成配对二维码：

```bash
source ~/.venvs/aizz/bin/activate
aizz pair --url http://192.168.1.10:8000
```

将示例 IP 替换为服务端电脑的实际内网 IP；不要填写监听地址 `0.0.0.0` 或手机自身的 `127.0.0.1`。手机需要能访问该地址，防火墙需允许对应端口。

打开 AIZZ APP 扫描二维码，核对地址和设备名后连接；也可以手动输入服务器地址和终端中的 6 位授权码。配对码五分钟有效、只能使用一次，新生成的码会使旧码失效。每台设备分别生成配对码，连接成功后 APP 自动保存凭证并在下次打开时重连。

支持 HTTP 和 HTTPS 源地址，可带端口，不支持 `/assistant` 等路径前缀。HTTP 配对前 APP 会提示风险：HTTP 明文传输配对码、设备凭证及聊天、图片和终端内容，凭证被窃取后可能被用于读取文件和执行命令。建议远程访问使用 HTTPS。

HTTPS 需要自行配置反向代理和设备信任的证书，再使用对应地址配对：

```bash
aizz pair --url https://your-server.example.com
```

代理需要支持流式响应和 `/api/terminal` 的 WebSocket 升级，并转发协议与客户端地址；代理在其他机器时，用 `aizz serve --forwarded-allow-ips <代理IP>` 指定实际可信的代理。只允许 HTTPS 访问的部署，应阻止外部绕过代理直接连接 HTTP 后端。二维码不提供网络穿透，也不会自动申请证书。

## 配置与数据

`~` 指运行服务端的系统用户主目录。服务端配置、设备授权与聊天数据默认保存在：

```text
~/.aizz/
├── config.json             # 聊天 Provider、模型和可选功能配置
├── workspaces.json         # 可选工作目录
├── tool_policy.json        # 普通聊天工具和命令权限
├── CHAT_INSTRUCTIONS.md    # 自定义聊天指令
├── CHAT_MEMORY.md          # 长期知识
├── assistant.db            # 设备授权、会话及任务数据
└── skills/                 # 可选的本地聊天 skills
```

### Codex 登录与工作目录

Codex 配置和登录目录默认是 `~/.codex`，设置 `CODEX_HOME` 后沿用指定目录。它与 AIZZ 配置目录 `~/.aizz` 分开，AIZZ 不会自动登录 Codex。

任务的默认工作目录是用户主目录 `~`。修改 `~/.aizz/workspaces.json`，可以限制为自己已有的项目目录：

```json
{
  "default": "~/code/my-project",
  "directories": ["~/code/another-project"]
}
```

目录必须事先存在，`default` 会自动加入可选列表。APP 设置中的项目目录入口也可以管理目录，修改后刷新 Workdir 即可生效。

需要在 APP 中选择多个 Codex 登录目录时，将以下字段合并到 `config.json`：

```json
{
  "codex": {
    "timeout_seconds": 600,
    "homes": {
      "personal": "~/.codex-personal",
      "work": "~/.codex-work"
    }
  }
}
```

各目录需要提前创建并分别完成 Codex 登录。切换账号目录不会自动登录或轮换账号。

### 聊天 Provider 与模型

默认 Provider 使用内置 Codex 对接。普通聊天的模型列表读取 `config.json` 中各 Provider 的 `models`；Codex 模式的模型列表由本机 CLI 提供。

使用其他 OpenAI 兼容聊天服务时，可将以下 Provider 合并到已有配置，并将 `active_provider` 改为其名称，或在 APP 设置中切换：

```json
{
  "active_provider": "custom",
  "providers": {
    "custom": {
      "base_url": "https://your-provider.example.com/v1",
      "api_key_env": "AIZZ_CHAT_API_KEY",
      "models": ["your-model-id"]
    }
  }
}
```

将地址和模型替换为实际服务支持的值，在启动服务端的终端中设置密钥环境变量：

```bash
export AIZZ_CHAT_API_KEY='<你的服务密钥>'
aizz serve
```

`models` 必须是非空数组；新增 Provider 时保留需要继续使用的原有 Provider 和其他配置项。密钥只在服务端配置，不需要填入 APP；修改环境变量后需要重新启动服务端。

### 环境变量

| 变量 | 用途 / 默认值 |
| --- | --- |
| `ASSISTANT_CONFIG` | 主配置文件，默认 `~/.aizz/config.json` |
| `ASSISTANT_WORKSPACES` | 工作目录配置，默认 `~/.aizz/workspaces.json` |
| `ASSISTANT_DB` | 数据库，默认 `~/.aizz/assistant.db` |
| `CODEX_HOME` | Codex 配置和登录目录，默认 `~/.codex` |
| `ASSISTANT_DEBUG` | 设为 `1` 开启应用调试日志 |

自定义配置或数据库路径时，启动和配对命令必须使用一致的环境变量。内置聊天代理另兼容 `CODE_HOME`，其登录目录优先级高于 `CODEX_HOME`；一般保持未设置即可。

图片生成、联网搜索及 iPhone 任务通知需要额外的服务或密钥配置，基础聊天和 Codex 任务不依赖这些可选功能。详细配置见[服务端使用说明](https://github.com/362228416/aizz-server#readme)。

## 设备管理与升级

```bash
aizz devices list
aizz devices revoke --id <设备ID>
# 撤销全部设备：
aizz devices revoke --all
```

所有授权设备共享同一个私人助手，具有相同管理权限。撤销设备后其凭证失效，重新连接需要新的配对码。

升级前先手动停止服务端，再在对应虚拟环境中执行：

```bash
python -m pip install --upgrade aizz-server
aizz --version
aizz serve
```

升级安装保留 `~/.aizz/` 下的配置与聊天记录；建议升级前备份该目录。已有源码部署的私人数据迁移方式见服务端使用说明。
