# panel

**Repository Path**: webvip/panel

## Basic Information

- **Project Name**: panel
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Panel

Panel 是用于管理 Frappe Bench 的命令行工具和 Web 管理界面。它以一个
`bench.toml` 描述单个 Bench 的运行配置，可完成初始化、应用和站点管理、日志与
任务查看、备份、监控及生产部署。

管理界面使用 React、TypeScript、Vite、shadcn/ui 和 Tailwind 构建；生产环境仍由
Panel 的 Flask 后端提供静态单页应用，不需要单独运行 Node.js 服务。

## 特性

- `bench.toml` 集中保存 Bench、数据库、Redis、工作进程和管理界面配置。
- 支持 MariaDB、PostgreSQL 和 SQLite 站点数据库。
- 支持创建、恢复、迁移、备份和删除站点，以及安装、更新和卸载应用。
- 内置应用市场、Git 仓库安装、任务流、日志、监控和 SQL 查询工具。
- 使用 `uv` 管理 Python 环境；应用的前端资源仍按 Frappe 约定使用 Yarn。
- Panel 管理前端使用锁定版本的 pnpm，支持英语和简体中文。

## 系统要求

- Debian 12+、Ubuntu 22.04+、Fedora 40+、Arch Linux、Alpine 3.20+，或 macOS。
- Python 3.11 或更高版本。
- Linux 生产环境需要 `sudo`；安装器会处理所需系统依赖。
- macOS 仅建议用于开发，需要 [Homebrew](https://brew.sh)。

Linux Mint、EndeavourOS 等声明了 `ID_LIKE` 的衍生发行版会按其上游发行版处理。

## 安装

推荐使用安装器：

```bash
curl -fsSL https://cnb.cool/frappe/panel/-/git/raw/main/install.sh | bash
```

在没有 curl 的精简系统中可使用：

```sh
wget -qO- https://cnb.cool/frappe/panel/-/git/raw/main/install.sh | sh
```

安装器会克隆 Panel 至 `~/panel`、配置 `bench` 命令、安装 `uv` 与 Node.js，并创建
供管理后端使用的 `.admin-venv`。管理后端依赖默认优先使用华为云 PyPI 镜像；如需改用
其他镜像，可在执行安装器时设置 `PANEL_PYPI_INDEX`。

### 安装 develop 分支

`develop` 包含尚未合并到 `main` 的开发改动，仅用于测试或预发布环境。首次安装时运行：

```bash
curl -fsSL https://cnb.cool/frappe/panel/-/git/raw/develop/install.sh | \
  PANEL_BRANCH=develop bash
```

安装器发现已有 `~/panel` 时只会拉取当前检出的分支，不会自动切换分支。若要将已有
安装切换到 `develop`，先执行：

```bash
git -C ~/panel fetch origin
git -C ~/panel checkout develop
git -C ~/panel pull --ff-only
```

生产环境应继续使用 `main` 分支的安装命令。

### 以 root 身份安装

不要直接以 root 运行 Bench。若安装器以 root 启动，它会创建或复用非 root 用户
（默认 `frappe`），赋予该用户无密码 sudo，并以该用户继续安装。

### 无交互安装

```bash
curl -fsSL https://cnb.cool/frappe/panel/-/git/raw/main/install.sh | \
  bash -s -- --user frappe --yes
```

| 参数            | 环境变量      | 说明                                                 |
| --------------- | ------------- | ---------------------------------------------------- |
| `--user <名称>` | `BENCH_USER`  | root 安装时使用或创建的非 root 用户，默认 `frappe`。 |
| `--yes`、`-y`   | `BENCH_YES=1` | 接受默认值且不再询问。                               |

### 从源码安装

```bash
git clone https://cnb.cool/frappe/panel ~/panel
echo 'export PATH="$HOME/panel:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

仓库根目录的 `bench` 启动器会优先使用项目 `.venv` 中的 Python；这可避免系统
Python 版本较旧时无法运行 Panel。

## 创建第一个 Bench

```bash
bench new my-bench
bench -b my-bench start
```

第一次启动会打开初始化向导。向导地址会在命令输出中显示，端口由 `bench new`
自动分配，以避免多个 Bench 相互冲突。向导依次配置：

1. 管理界面密码；
2. 数据库类型、管理员账号与密码；
3. Frappe 仓库和分支。

完成后，Bench 会初始化 Frappe 环境并启动管理界面。若只有一个 Bench，很多命令可
省略 `-b my-bench`；在脚本或多 Bench 环境中建议始终显式指定。

### 手动初始化

```bash
bench new my-bench
$EDITOR benches/my-bench/bench.toml
bench -b my-bench init
bench -b my-bench get-app https://github.com/frappe/erpnext --branch version-16
bench -b my-bench new-site site1.localhost
bench -b my-bench start
```

`bench.toml` 中的管理员密码、数据库管理员密码等敏感值只应存放在受保护的主机上，
不得提交到版本库。

## 常用命令

| 命令                                      | 说明                                             |
| ----------------------------------------- | ------------------------------------------------ |
| `bench new <名称>`                        | 创建 Bench 目录和初始 `bench.toml`。             |
| `bench ls`                                | 列出 Bench、状态和管理地址。                     |
| `bench -b <名称> init`                    | 安装依赖、创建环境、克隆 Frappe 并生成运行配置。 |
| `bench -b <名称> start`                   | 前台启动 Bench；未初始化时启动向导。             |
| `bench -b <名称> stop`                    | 停止运行中的 Bench。                             |
| `bench -b <名称> restart`                 | 重启生产环境进程。                               |
| `bench -b <名称> get-app <仓库>`          | 克隆并安装应用。                                 |
| `bench -b <名称> new-site <名称>`         | 创建站点。                                       |
| `bench -b <名称> rename-site <旧> <新>`   | 重命名站点。                                     |
| `bench -b <名称> build`                   | 构建已安装应用的资源。                           |
| `bench build-admin`                       | 下载或从源码重新构建 Panel 管理前端。            |
| `bench -b <名称> update`                  | 更新应用、依赖、资源并迁移站点。                 |
| `bench upgrade`                           | 更新 Panel 并获取最新管理前端。                  |
| `bench -b <名称> set-admin-password`      | 设置管理界面密码。                               |
| `bench -b <名称> generate-admin-session`  | 生成一次性管理登录链接。                         |
| `bench -b <名称> issue-site-token <站点>` | 生成站点范围的 API JWT。                         |
| `bench -b <名称> setup production`        | 配置生产进程、反向代理和可选 TLS。               |
| `bench -b <名称> remove production`       | 移除生产配置并回到开发模式。                     |
| `bench -b <名称> drop --yes`              | 删除没有站点的 Bench。                           |

完整参数请运行 `bench --help` 或查阅 [命令说明](docs/commands.md)。

## 配置示例

`bench new` 会生成完整配置，以下为常用字段示意：

```toml
[bench]
name = "my-bench"
python = "3.14"

[[apps]]
name = "frappe"
repo = "https://cnb.cool/frappe/frappe"
branch = "version-16"

[mariadb]
host = "localhost"
port = 3306
root_password = "请使用安全密码"

[redis]
port = 13000

[admin]
password = "请使用安全密码"
domain = ""
tls = false

[production]
enabled = false
process_manager = ""
```

端口会随 Bench 自动偏移；请以实际 `benches/<名称>/bench.toml` 为准。

## 管理前端开发

先在一个已创建的 Bench 上启动后端：

```bash
bench -b my-bench start
```

另开终端启动 React 前端：

```bash
cd admin/frontend
BACKEND_PROXY_URL=http://localhost:7001 pnpm dev
```

Vite 默认监听 `http://localhost:5174`。请将 `BACKEND_PROXY_URL` 替换为该 Bench
实际显示的管理端口。生产构建直接输出到 Flask 使用的
`admin/backend/static/dist`：

```bash
cd admin/frontend
pnpm install --frozen-lockfile
pnpm test --run
pnpm typecheck
pnpm lint
pnpm build
```

前端目录说明：

- `src/app`：路由、会话、主题和多语言上下文；
- `src/features`：按业务模块组织的页面和交互；
- `src/components/ui`：shadcn/ui 基础组件；
- `src/api`：Panel Flask API 客户端。

新用户可见文案必须通过 `useTranslation()` 使用翻译字典；当前支持英语和简体中文。

## 生产部署

生产配置会选择 systemd、Supervisor 或 OpenRC，并生成必要的反向代理配置。示例：

```bash
bench -b my-bench setup production --admin-domain admin.example.com --tls
bench -b my-bench restart
```

启用 TLS 时，Panel 使用 Let's Encrypt 为管理域名和已启用 SSL 的站点申请证书。若由
上游代理终止 TLS，可不传 `--tls`。

生产前请确认 DNS 已指向目标服务器，并阅读
[架构说明](docs/architecture.md) 与 [管理界面说明](docs/admin.md)。

## 目录结构

```text
panel/
├── admin/
│   ├── backend/       Flask 管理 API 和静态文件服务
│   └── frontend/      React 管理前端
├── panel/             CLI、配置、领域模型和进程管理
├── benches/           已创建的 Bench（运行时数据）
├── registry/          应用市场注册表
├── tests/             单元、集成和浏览器测试
└── docs/              设计、命令和运维文档
```

单个 Bench 的主要内容位于 `benches/<名称>/`：`bench.toml`、`apps/`、`sites/`、`env/`、
`logs/`、`pids/` 和 `config/`。

## 应用市场贡献

在 `registry/apps.json` 中添加应用条目并提交合并请求。条目至少包含 `name`、`title`、
`description`、`repo`、`branch`、`branches` 和 `category`；可选字段包括 `logo_url` 与
`stars`。

市场注册表变更会触发应用源码安全扫描。阻断性检查包括代码注入、模板注入、SQL 注入、
危险命令执行、权限绕过和多租户隔离问题。

## 测试

```bash
# 安装测试与管理后端依赖
uv pip install --python .venv/bin/python -e ".[test,admin]"

# 运行适用的单元测试
.venv/bin/python -m pytest tests/ --ignore=tests/integration --ignore=tests/e2e -q

# 前端质量门禁
cd admin/frontend
pnpm test --run
pnpm typecheck
pnpm lint
pnpm build
```

浏览器生命周期测试需要 Redis、MariaDB 或 PostgreSQL、Playwright 和 Chromium：

```bash
uv pip install --python .venv/bin/python -e ".[e2e]"
.venv/bin/python -m playwright install chromium
.venv/bin/python -m pytest tests/e2e
```

更多测试前提和环境变量请阅读 [E2E 说明](tests/e2e/README.md)。

## 文档与贡献

- [命令说明](docs/commands.md)
- [架构说明](docs/architecture.md)
- [管理界面说明](docs/admin.md)
- [前端迁移规范](docs/frontend-migration-spec.md)
- [更新日志](CHANGELOG.md)
- [贡献规范](AGENTS.md)

提交前请保持改动聚焦、补充相应测试。提交信息与 PR 标题使用 Conventional
Commits 的英文类型前缀和中文说明，例如 `feat: 增加站点导出`。

### 发布流程

功能开发提交至 `develop`，通过 CI 后创建 `develop → main` 的 PR。合并到 `main`
后，带 `feat`、`fix`、`perf` 或 `revert` 前缀的提交会触发 semantic-release：它根据
提交类型生成版本标签和更新日志，再由标签流水线构建并发布 Python 制品。`chore`、`docs`
和 `test` 提交不会创建版本。