SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbtpanel_ai_site

btpanel_ai_site

Deployment & operations

View repository

Updated 10-15 11:02

About this skill

You are a BT Panel AI project website building expert, helping users deploy project code to the BT Panel and integrate it into the AI project management system. This skill is currently only used to process project_type='AI' projects and websites.

Mandatory constraints

When the user explicitly mentions "AI project", "AI website building", "AI site", or needs to integrate a project into the panel AI management system, the following must be strictly observed:

  • Use only the scripts and processes of this skill: All website building operations are completed through btpython scripts/ai_site.py .
  • Other website building methods are prohibited: Do not use the PHP site skill (btpanel_site/php_site.py), HTML site skill (html_site.py), reverse proxy skill (proxy_site.py), or any panel built-in addsite tool to create AI projects
  • AI projects are isolated from other project types: AI projects' project_type='AI'have an independent configuration system (ai_config.json), Nginx configuration naming (ai_{name}.conf), and management process. Mixing other website building methods will cause the project to fail to be correctly recognized and controlled by the AI management module.

Directory structure

btpanel_ai_site/
├── SKILL.md                       # 本文件:建站流程指南和核心规则
├── scripts/
│   └── ai_site.py                 # AI项目操作封装脚本(执行而不读入上下文)
└── references/
    ├── create_project.md          # create_project 接口完整参数文档(按需加载)
    └── other_apis.md              # 其余接口速查(项目控制/域名/日志/修改/删除/SSL 按需加载)

Core concepts

Two project modes

Mode project_mode Description Applicable scenarios
Dynamic project dynamic A backend service with port listening, whose process is managed through start/stop commands Backend projects such as Node.js, Python Flask, Go, etc.
Static project static Pure static files, directly hosted by Nginx Pure frontend projects after Vue/React packaging

ai_config.json — the configuration bridge between AI and the panel

All project configurations are stored in {project_path}/.aiproject/ai_config.json, and the panel dynamically recognizes this file at runtime. AI manages the configuration by directly reading and writing this file, without scripts or interfaces.

.aiproject/ The directory is intercepted by Nginx (externally returns 404), and the internal configuration is securely isolated.

Key conventions

  • project_name Only letters, numbers, and underscores are supported
  • Panel reserved names (default、localhost) cannot be used
  • Project names are globally unique and cannot be created repeatedly
  • AI first creates the project directory and code files, then calls the script to integrate into the panel
  • Dynamic projects must provide ports、start_cmd、stop_cmd
  • Run user: When there are no special requirements, projects uniformly use the www user to run (--run_user www). This is both the panel default value and a security best practice—avoid running user code with root permissions
  • Service port binding: Non-website ports (backend API, frontend dev server, etc.) bind to 127.0.0.1by default, and provide services externally only through Nginx reverse proxy. If the service listens on 0.0.0.0, the port will be directly exposed on the public network, forming two entry points with Nginx and increasing security risks. Unless the user explicitly requests direct external access to a port, or it has been confirmed with the user and the risks have been communicated, 0.0.0.0 binding should not be used
  • Project logs: If the project is started through a service, service logs must be provided (you may use > &log_file, or configure log output in the code), and the log file path must be specified under the .aiproject/ directory, and configured in ai_config.json as the log path (specified inlogs )
  • After the project is completed, you must create or update README.mdin the project root directory, recording core information such as project architecture, directory structure, startup method, port usage, core configuration, important dependencies, and key business processes, so that the project can be quickly understood later
  • When modifying the project later, you must synchronously update README.md, ensuring the documentation reflects the latest architecture, structure, configuration, running method, and key changes

Pre-site-building check process (must be executed)

Before creating a project, AI must complete the following checks in order, and must not skip them.

Step 1: Check the environment required by the project

According to the type of project being deployed, check whether the required environment components are already installed on the server:

Checklist

Project Type Required Environment Optional Environment
Node.js Project Node.js、Nginx MySQL、Redis、PM2
Python Project Python、Nginx MySQL、Redis、pip
Go Project Nginx MySQL、Redis
PHP Project PHP、Nginx、PHP-FPM MySQL、Redis、Composer
Static Project Nginx —
Java Project JDK、Nginx MySQL、Redis、Maven

Handling process when the environment is not installed

  1. Report the missing environment components to the user, clearly listing which environments are not installed
  2. Explain why the project needs these environments(e.g., a Node.js project needs Node to run the backend service and needs Nginx as a reverse proxy)
  3. Propose installation suggestions to the user, and explain that the corresponding skill tool will be used for installation
  4. After obtaining the user's explicit consent, then call the corresponding skill tool to perform the installation

Important: Without the user's explicit consent, you must not install any environment components without authorization.

Step 2: Check for domain and directory conflicts

Before creating a project, you must check whether the following content has conflicts:

2.1 Domain conflict check

Check whether the domain provided by the user is already occupied by another site or AI project:

Handling process when a conflict is found:

  1. Report the conflict to the user, explaining which project/site already occupies the domain
  2. Provide solutions for the user to choose from:
    • Option A: Change to a new domain
    • Option B: Delete the old project/site occupying the domain (requires user confirmation)
    • Option C: Add the new project under a different path of the existing domain (if applicable)
  3. After waiting for the user to choose and explicitly agree, then perform the corresponding operation

2.2 Directory conflict check

Check whether the project path specified by the user already exists:

Handling process when a conflict is found:

  1. Report to the user that the directory already exists, explaining the directory path and current contents
  2. Provide solutions for the user to choose from:
    • Option A: Use another path (e.g., /www/wwwroot/my_project_v2)
    • Option B: Clear the existing directory (⚠️ will delete all files in the directory, requires user confirmation)
    • Option C: Continue creating in the existing directory (only when the directory is empty or the user confirms overwriting)
  3. After waiting for the user to choose and explicitly agree, then perform the corresponding operation

Important:

  • Without the user's explicit consent, no existing files/directories may be deleted or overwritten without authorization
  • When deletion operations are involved, the risks must be confirmed with the user again
  • All conflict situations must be reported to the user and must not be concealed or handled automatically

Website building scenarios

Scenario A: Dynamic projects (Node.js / Python / Go backend)

步骤 1: 执行建站前置检查流程
  - 检查所需环境(Nginx、Node.js/Python/Go 等)
  - 检查域名冲突(example.com 是否被占用)
  - 检查目录冲突(/www/wwwroot/my_project 是否存在)
  - 发现冲突时向用户报告并获得同意后处理

步骤 2: 创建项目目录和代码文件
  mkdir -p /www/wwwroot/my_project
  # 写入项目代码(package.json / server.js / requirements.txt 等)

步骤 3: 安装依赖
  cd /www/wwwroot/my_project && npm install  # 或其他依赖安装

步骤 4: 调用 create 脚本接入面板
  btpython scripts/ai_site.py create \
    --project_name my_project \
    --project_path /www/wwwroot/my_project \
    --project_mode dynamic \
    --ports '[{"port":3000,"label":"Web服务"}]' \
    --start_cmd "cd /www/wwwroot/my_project && npm run start" \
    --stop_cmd "cd /www/wwwroot/my_project && npm run stop" \
    --domains '["example.com:80"]' \
    --run_user www \
    --is_power_on 0 \
    --environment "NODE_ENV=production" \
    --logs '{"后端服务":"/www/wwwroot/my_project/.aiproject/backend.log"}' \
    --project_ps "项目备注"

步骤 5: 面板自动处理
  - 写入 ai_config.json
  - 写入数据库
  - 生成 Nginx 反向代理配置
  - 重载 Nginx
  - 执行启动命令
  - 项目运行中 ✓

Before calling, must load references/create_project.md to obtain the complete parameter rules.

Scenario B: Static projects (pure frontend after Vue / React build)

步骤 1: 执行建站前置检查流程
  - 检查所需环境(Nginx)
  - 检查域名冲突(static.example.com 是否被占用)
  - 检查目录冲突(/www/wwwroot/my_static_site 是否存在)
  - 发现冲突时向用户报告并获得同意后处理

步骤 2: 创建项目目录和静态文件
  mkdir -p /www/wwwroot/my_static_site
  # 写入 index.html 等静态文件

步骤 3: 调用 create 脚本接入面板
  btpython scripts/ai_site.py create \
    --project_name my_static_site \
    --project_path /www/wwwroot/my_static_site \
    --project_mode static \
    --domains '["static.example.com:80"]' \
    --project_ps "项目备注"

步骤 4: 面板自动处理
  - 写入配置
  - 生成 Nginx 静态托管配置
  - 重载 Nginx
  - 项目运行中 ✓

Static projects do not need ports、start_cmd、stop_cmd. Nginx directly hosts static files.

Scenario C: Multi-port microservice projects

步骤 1: 执行建站前置检查流程
  - 检查所需环境(Nginx、Node.js 等)
  - 检查域名冲突(api.example.com 是否被占用)
  - 检查目录冲突(/www/wwwroot/micro_service 是否存在)
  - 发现冲突时向用户报告并获得同意后处理

步骤 2: 创建项目并接入面板
btpython scripts/ai_site.py create \
  --project_name micro_service \
  --project_path /www/wwwroot/micro_service \
  --project_mode dynamic \
  --ports '[{"port":3000,"label":"前端服务"},{"port":3001,"label":"后端API"},{"port":3002,"label":"WebSocket"}]' \
  --start_cmd "cd /www/wwwroot/micro_service && bash start_all.sh" \
  --stop_cmd "cd /www/wwwroot/micro_service && bash stop_all.sh" \
  --domains '["api.example.com:80"]' \
  --logs '{"前端服务":".aiproject/frontend.log","后端服务":".aiproject/backend.log","API服务":".aiproject/api.log"}' \
  --project_ps "项目备注"

ports[0] (3000/frontend service) is primary_port. AI needs to pass start_all.sh to start multiple services simultaneously.

Script command quick reference

All operations are executed through btpython scripts/ai_site.py <子命令> :

Subcommand Function Example
create Create project btpython scripts/ai_site.py create --project_name xxx --project_path /www/wwwroot/xxx --project_mode dynamic --ports '[{"port":3000,"label":"Web服务"}]' --start_cmd "..." --stop_cmd "..."
modify Modify project btpython scripts/ai_site.py modify --project_name xxx --ports '[{"port":3001,"label":"API服务"}]'
remove Delete project btpython scripts/ai_site.py remove --project_name xxx
start Start project btpython scripts/ai_site.py start --project_name xxx
stop Stop project btpython scripts/ai_site.py stop --project_name xxx
restart Restart project btpython scripts/ai_site.py restart --project_name xxx
list Project list btpython scripts/ai_site.py list
stat Project status btpython scripts/ai_site.py stat --project_name xxx
add-domain Add domain btpython scripts/ai_site.py add-domain --project_name xxx --domain example.com:443
del-domain Delete domain btpython scripts/ai_site.py del-domain --project_name xxx --domain example.com
get-domain Get domain list btpython scripts/ai_site.py get-domain --project_name xxx
log-list Log list btpython scripts/ai_site.py log-list --project_name xxx
log-content View logs btpython scripts/ai_site.py log-content --project_name xxx --log_path /path/to/log --lines 100

For detailed parameters and return values, see the references/ documentation. Load the corresponding documentation as needed before execution.

Configuration management — directly edit ai_config.json

The following operations require no script; AI directly reads and writes {project_path}/.aiproject/ai_config.json:

Complete field description

{
    "ssl_path": "/www/wwwroot/ai_ssl/my_project",
    "project_name": "my_project",
    "project_path": "/www/wwwroot/my_project",
    "ports": [{"port": 3000, "label": "Web服务"}, {"port": 3001, "label": "API服务"}],
    "primary_port": 3000,
    "start_cmd": "cd /www/wwwroot/my_project && npm run start",
    "stop_cmd": "cd /www/wwwroot/my_project && npm run stop",
    "is_power_on": 0,
    "run_user": "www",
    "project_mode": "dynamic",
    "domains": ["example.com:80", "www.example.com:80"],
    "environment": "NODE_ENV=production",
    "logs": {
        "access_log": "/www/wwwlogs/ai/my_project_access.log",
        "error_log": "/www/wwwlogs/ai/my_project_error.log",
        "后端服务": "/www/wwwroot/my_project/.aiproject/backend.log"
    }
}

access_log and error_log are automatically generated by the panel; AI does not need to fill them in.logs In , only configure the project's own business log categories.

AI can modify the configuration by directly editing this JSON file using file read/write tools. The panel dynamically detects changes; no restart is required after modification.

Must do

  1. Before creating a project, the pre-site-building check process must be executed(environment check + conflict detection), and cannot be skipped
  2. When missing environment components are found, they must be reported to the user and explicit consent must be obtained before installation
  3. When domain or directory conflicts are found, they must be reported to the user and a solution must be provided; execution may proceed only after obtaining the user's consent
  4. First create the project directory and code files, then call create script
  5. Dynamic projects must provide ports、start_cmd、stop_cmd
  6. Ensure the port is available (the panel will detect port occupation)
  7. The domain must be resolved to the server IP in advance (otherwise the SSL application will fail)
  8. Place the log file path under the .aiproject/ directory. Dynamic projects need to configure log categories in logs configure log categories in
  9. After the project is completed, must create or update in the project root directory README.md, recording core information such as project architecture, directory structure, startup method, port usage, core configuration, important dependencies, and key business processes
  10. When modifying the project later, must synchronously update README.md, ensuring the documentation reflects the latest architecture, structure, configuration, running method, and key changes
  11. Before calling create load references/create_project.md to obtain the complete parameter rules

Dynamic projects — Nginx reverse proxy configuration

The Nginx configuration file for dynamic projects is located at /www/server/panel/vhost/nginx/ai_{project_name}.conf。

If a project runs multiple ports (e.g., the frontend, backend, and API each occupy a port), reverse proxies are not automatically generated for the ports. In this case, you need to edit the Nginx configuration file and add a location block to proxy a specific path to the corresponding port. After editing, reload Nginx for the changes to take effect:

/etc/init.d/nginx reload  # 或 nginx -s reload

Example — Add to the project a /api path proxied to port 3001:

location /api {
    proxy_pass http://127.0.0.1:3001;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

References loading guide

  • Before creating a project — load references/create_project.md to learn the complete parameter rules
  • When you need to control a project/manage domains/view logs/modify or delete — load references/other_apis.md
  • Need to modify configuration — edit directly ai_config.json, refer to the field descriptions above