CNWei
37479f48c7
- README：三栏工作台与弹窗说明、uv 路径默认值（python / uv-cache）、镜像只在装包时生效、API 与数据布局、测试现状注记 - RELEASE：补 uv-cache 与 uv 目录、配置入口改为弹窗、运行时注入说明 - 新增 ADR-0009：uv 与托管 Python 环境的决策与边界 - PLAN：补记已完成的后继迭代
77 lines
3.5 KiB
Markdown
77 lines
3.5 KiB
Markdown
# TaskPilot Windows 本地版
|
||
|
||
## 启动
|
||
|
||
```powershell
|
||
.\start.ps1
|
||
```
|
||
|
||
然后访问 <http://127.0.0.1:3000>。
|
||
|
||
需要自动打开浏览器时：
|
||
|
||
```powershell
|
||
.\start.ps1 -OpenBrowser
|
||
```
|
||
|
||
## 数据目录
|
||
|
||
- SQLite 数据库：`data/task_pilot.db`（WAL 模式，运行中会额外出现 `-wal`/`-shm` 文件）
|
||
- 运行日志：`logs/{task_id}/{run_id}.log`
|
||
- 托管虚拟环境：`data/envs/<名称>/`（「虚拟环境」弹窗创建，删除环境就是删掉整个目录）
|
||
- uv 下载的 Python 解释器：`python/<版本>/`
|
||
- uv 缓存：`uv-cache/`（首次装包/下载 Python 后才会出现）
|
||
- 程序下载的 uv：`uv/uv.exe`
|
||
|
||
`UV_PYTHON_INSTALL_DIR` 与 `UV_CACHE_DIR` 默认是**相对本目录**的 `python` / `uv-cache`，
|
||
整个发布目录可以整体搬走；想复用机器上的全局缓存，在 uv 配置弹窗里把这两个变量改成绝对路径。
|
||
|
||
## Python 与 uv
|
||
|
||
用 uv 创建虚拟环境时，uv 的来源在 uv 配置弹窗（任务调度页右栏「uv → 配置」）切换（不读系统 PATH）：
|
||
|
||
- 本目录下的 `uv/uv.exe`（默认）：没有 uv 时会出现「下载 uv」，会从科大镜像下载并校验 sha256 后放进来；也可以自己下载后放到这里
|
||
- 任意位置的 `uv.exe`：选「指定路径」，保存时会先校验能运行；本机已装 uv 就把它的路径填进来
|
||
|
||
同一弹窗还能配置 `UV_*` 环境变量（如 `UV_CACHE_DIR`、`UV_PYTHON_INSTALL_DIR`），会注入到每一次 uv 调用；
|
||
任务运行时会把这些变量和默认镜像 `UV_DEFAULT_INDEX` 一并注入任务进程（任务自己的环境变量优先）。
|
||
|
||
「下载 uv」依赖 `mirrors.ustc.edu.cn` 可达；离线环境请自己准备 uv 并指定路径。
|
||
|
||
## 配置
|
||
|
||
```powershell
|
||
$env:TASK_PILOT_PORT = "3000"
|
||
$env:TASK_PILOT_DATABASE_URL = "sqlite://data/task_pilot.db"
|
||
$env:TASK_PILOT_LOG_DIR = "logs"
|
||
$env:TASK_PILOT_LOG_RETENTION_DAYS = "30"
|
||
$env:TASK_PILOT_LOG_MAX_TOTAL_MB = "512"
|
||
$env:TASK_PILOT_LOG_ENCODING = "auto"
|
||
$env:TASK_PILOT_STATIC_DIR = "web"
|
||
```
|
||
|
||
`TASK_PILOT_LOG_ENCODING` 默认 `auto`，会按 UTF-8 → 系统 ANSI 代码页（简体中文为 GBK）的顺序解码子进程输出；日志出现乱码时可显式指定 `gbk` 或 `utf-8`。
|
||
|
||
单次运行日志上限 5 MiB，单行上限 256 KiB；日志按保留期与总容量清理，正在写入的文件不会被删除。
|
||
|
||
## 安全边界
|
||
|
||
- 服务只监听 `127.0.0.1`。
|
||
- 浏览器跨站 Origin 会被拒绝。
|
||
- 写操作需要运行期随机管理令牌，进程重启后自动更换。
|
||
- 请求体上限 2 MiB。
|
||
|
||
## 离线使用
|
||
|
||
前端资源、字体（`LXGW WenKai` / `Outfit-Medium`）与所有脚本都随包自带，不需要联网即可打开界面与执行任务。
|
||
|
||
## 故障排查
|
||
|
||
- 3000 端口被占用时，通过 `TASK_PILOT_PORT` 修改端口；打包版前端使用同源 API，无需重新构建。
|
||
- 页面无法打开时，确认 `web/index.html` 存在。
|
||
- 任务未执行时，确认任务已启用、Cron 正确，并在任务表的「调度周期」列查看下次触发时间。
|
||
- PowerShell 脚本任务报「不是数字签名」时，是执行策略拦截未签名脚本：在参数里加 `-ExecutionPolicy Bypass`，或对脚本目录执行 `Unblock-File`。
|
||
- 进程无法启动时，检查解释器或可执行文件路径、工作目录和执行权限。
|
||
- 日志里出现 `����`：改用 UTF-8 输出，或设置 `TASK_PILOT_LOG_ENCODING=gbk`。
|
||
- 进程被强杀后，遗留的运行会在下次启动时标记为「已取消（进程重启中断）」，不是数据损坏。
|