Qinglong

https://github.com/whyour/qinglong
Admin
Qinglong is a timed task management platform supporting Python3, JavaScript, Shell, and TypeScript...
Tokens:110,454
Snippets:741
Trust Score:9.8
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Setup Qinglong Development Environment

Source: https://github.com/whyour/qinglong/blob/develop/README-en.md

Clone the repository, copy the environment file, install pnpm 8.3.1 globally, install dependencies, and start the development server. After running these commands, open http://127.0.0.1:5700 in your browser.

```bash
git clone https://github.com/whyour/qinglong.git
cd qinglong
cp .env.example .env
# Recommended use pnpm https://pnpm.io/zh/installation
npm install -g pnpm@8.3.1
pnpm install
pnpm start
```

--------------------------------

### Start development server with pnpm start

Source: https://github.com/whyour/qinglong/blob/develop/docs/PROJECT_ARCHITECTURE.md

Runs the development environment. Executes the start:back and start:front scripts, which run nodemon on back/app.ts and max dev respectively.

```bash
pnpm start
```

--------------------------------

### Install and check CLI help

Source: https://github.com/whyour/qinglong/blob/develop/cli/README.en.md

Install the @whyour/qinglong-cli package globally and verify the CLI works. The npm exec command allows temporary use without replacing an existing panel ql. Requires Node >=22.12.

```sh
npm install -g @whyour/qinglong-cli
ql --help
# Temporary use without replacing an existing panel ql
npm exec --package=@whyour/qinglong-cli -- ql --help
```

--------------------------------

### Example usage of DependenceService

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/dependence.md

Example showing how to use the service to create, reinstall, and cancel dependencies. It demonstrates queueing, waiting, and error handling.

```typescript
import { Container } from 'typedi';
import DependenceService from '../services/dependence';
import { DependenceTypes } from '../data/dependence';

const depService = Container.get(DependenceService);

// queue installation of a node and a python package
await depService.create([
  { name: 'got', type: DependenceTypes.nodejs },
  { name: 'requests', type: DependenceTypes.python3, remark: 'web' },
]);

// wait for the queue, then force-reinstall one of them
await depService.installDependenceOneByOne([], true, false);
const reinstalled = await depService.reInstall([2]);
console.log(reinstalled.map((d) => d.status)); // queued -> installing -> installed via SockJS

// cancel a stuck install
try {
  await depService.cancel([1]);
} catch (e) {
  // killTask can throw 'Task processes did not exit: ...'
}
```

--------------------------------

### Usage example: create, run, and read log

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/subscription.md

Shows how to obtain the SubscriptionService from the DI container, create a repository subscription with hooks, run it immediately, and read the tail of its log. The example uses a crontab schedule and a whitelist pattern.

```typescript
import { Container } from 'typedi';
import SubscriptionService from '../services/subscription';

const subs = Container.get(SubscriptionService);

// create a repository subscription with hooks
await subs.create({
  type: 'public-repo',
  url: 'https://github.com/user/repo.git',
  alias: 'repo-a',
  schedule_type: 'crontab',
  schedule: '0 */6 * * *',
  whitelist: 'script___.py',
  sub_before: 'echo "starting pull"',
  sub_after: 'echo "finished pull"',
  autoAddCron: 1,
});

// run it immediately, then inspect the tail of the log
await subs.run([1]);
const chunk = await subs.log(1, { tail: true, limit: 1024 });
console.log(chunk.content);
```

--------------------------------

### Image registry overlay example

Source: https://github.com/whyour/qinglong/blob/develop/deploy/kubernetes/README.md

Shows the format for customizing the image registry in the example overlay. Replace the placeholder with your actual registry path.

```yaml
whyour/qinglong:debian -> registry.example.com/whyour/qinglong:debian
```

--------------------------------

### Password hashing example usage

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/auth.md

Example demonstrating hashPassword, isPasswordHash, and verifyPassword with a sample password.

```ts
import { hashPassword, verifyPassword } from '../shared/password';

const hash = await hashPassword('s3cret');
console.log(isPasswordHash(hash)); // true
const ok = await verifyPassword('s3cret', hash); // true

```

--------------------------------

### createCronJob usage example

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/cron-schedule.md

Example of creating and starting a cron job with a 5-minute interval. The job logs the date on each tick, and `job.cancel()` stops it later.

```typescript
import { createCronJob } from '../shared/cronScheduler';

const job = createCronJob(
  '*/5 * * * *',
  async (date) => console.log('tick', date.toISOString()),
  { name: 'example: heartbeat', logger: console, start: false },
);
job.start();
// later...
job.cancel();
```

--------------------------------

### Using observeChildProcess with cross-spawn

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/process-tools.md

Usage example for observeChildProcess with cross-spawn. Spawns a shell command, attaches onStart and onStdout callbacks, then awaits started (PID) and completed (result object).

```ts
import { spawn } from 'cross-spawn';
import { observeChildProcess } from '../shared/childProcess';

const cp = spawn('task demo.ts', { shell: '/bin/bash' });
const { started, completed } = observeChildProcess(cp, {
  onStart: async () => console.log('up'),
  onStdout: async (line) => console.log(line),
});
console.log(await started);          // pid
console.log(await completed);        // { code: 0, signal: null }
```

--------------------------------

### Remote management command examples

Source: https://github.com/whyour/qinglong/blob/develop/cli/README.en.md

A series of example commands for logging in, checking auth status, and managing tasks and subscriptions via the remote API. All commands use --json for structured output. The final command logs out.

```sh
ql login --url https://ql.example.com
ql auth status --json
ql task list --search example --page 1 --size 50 --json
ql task get 12 --json
ql task logs 12 --tail 200 --json
ql task run 12 --json
ql task stop 12 --json
ql auth status --scope subscriptions --json
ql subscription list --json
ql subscription get 5 --json
ql subscription run 5 --json
ql subscription stop 5 --json
ql subscription logs 5 --tail 200 --json
ql subscription enable 5 --json
ql subscription disable 5 --json
ql auth logout --json
```

--------------------------------

### EnvService usage example

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/env.md

Example of using EnvService to create environment variables, read them back, and perform bulk operations. Demonstrates error handling for missing IDs.

```typescript
import { Container } from 'typedi';
import EnvService from '../services/env';

const envService = Container.get(EnvService);

// create several variables then read them back
await envService.create([
  { name: 'ALIYUN_TOKEN', value: 'secret-1', remarks: 'main' },
  { name: 'ALIYUN_TOKEN', value: 'secret-2', remarks: 'backup' },
]);
const all = await envService.envs('ALIYUN');
console.log(all.map((e) => `${e.name}=${e.value}`)); // both rows; task runtime joins with '&'

// bulk renames with labels
try {
  await envService.updateNames({ ids: all.map((e) => e.id!), name: 'ALIYUN_TOKEN_V2' });
  await envService.addLabels(all.map((e) => e.id!), ['prod']);
} catch (e) {
  // getDb/update throw "Env ... not found" for missing ids
  console.error(e.message);
}
```

--------------------------------

### Install Qinglong via npm

Source: https://github.com/whyour/qinglong/blob/develop/README-en.md

Install the npm version. Requires debian/ubuntu/alpine systems with node, npm, python3, pip3, and pnpm installed.

```bash
npm i @whyour/qinglong
```

--------------------------------

### POST /api/dependencies

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Queues installation of dependencies. Statuses are streamed over SockJS.

```APIDOC
## POST /api/dependencies

### Description
Queues installation of dependencies. Statuses are streamed over SockJS.

### Method
POST

### Endpoint
/api/dependencies

### Parameters
#### Request Body
- **name** (string) - Required - Dependency name
- **type** (string) - Required - Dependency type
- **remark** (string) - Optional - Remark

### Request Example
[
  {
    "name": "example",
    "type": "node",
    "remark": "optional"
  }
]

### Response
#### Success Response (200)
- **message** (string) - Success message

#### Response Example
{
  "message": "success"
}
```

--------------------------------

### GET /api/configs/samples

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Retrieves a list of sample configuration files.

```APIDOC
## GET /api/configs/samples

### Description
Retrieves a list of sample configuration files.

### Method
GET

### Endpoint
/api/configs/samples

### Response
#### Success Response (200)
- **array** (array) - List of sample file names.

#### Response Example
```json
[
  "config.sample.sh",
  "notify.js",
  "notify.py"
]
```
```

--------------------------------

### GET /api/system/config

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Retrieves system configuration.

```APIDOC
## GET /api/system/config

### Description
Retrieves system configuration.

### Method
GET

### Endpoint
/api/system/config

### Response
#### Success Response (200)
- **systemConfig** (object) - System configuration document

#### Response Example
{
  "systemConfig": {}
}
```

--------------------------------

### PUT /api/dependencies/cancel

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Kills the install process and sets status to cancelled.

```APIDOC
## PUT /api/dependencies/cancel

### Description
Kills the install process and sets status to cancelled.

### Method
PUT

### Endpoint
/api/dependencies/cancel

### Parameters
#### Request Body
- **id** (array of string) - Required - Dependency IDs

### Request Example
[
  "123",
  "456"
]

### Response
#### Success Response (200)
- **message** (string) - Success message

#### Response Example
{
  "message": "success"
}
```

--------------------------------

### runTask usage example

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/schedule.md

Example call to runTask with lifecycle callbacks and completionTime set to 'start' to get the PID.

```typescript
const pid = await scheduleService.runTask(
  'task demo.ts',
  {
    onBefore: async () => console.log('starting'),
    onStart: async (cp) => console.log('pid', cp.pid),
    onLog: async (line) => appendLog(line),
    onEnd: async (cp, end, diff) => console.log(`took ${diff}s`),
  },
  { command: 'task demo.ts', id: 'demo', runOrigin: 'script' },
  'start',
);
```

--------------------------------

### Install and use the ql CLI to manage a remote QingLong panel

Source: https://github.com/whyour/qinglong/blob/develop/README-en.md

Install the package globally with npm, then log in to the panel and run commands with JSON output. Requires Node.js >=22.12; Node.js 24 is recommended. Create an application in the panel's System Settings and provide its credentials during login. Existing tokens are supported via QL_URL and QL_ACCESS_TOKEN.

```bash
npm install -g @whyour/qinglong-cli
ql login --url https://ql.example.com
ql auth status --json
ql task list --json
ql subscription list --json
ql --help
```

--------------------------------

### GET /api/dependencies

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Lists dependencies with optional filters and probes installed statuses.

```APIDOC
## GET /api/dependencies

### Description
Lists dependencies with optional filters and probes installed statuses.

### Method
GET

### Endpoint
/api/dependencies

### Parameters
#### Query Parameters
- **searchValue** (string) - Optional - Search value
- **type** (string) - Optional - Dependency type
- **status** (string) - Optional - Dependency status

### Response
#### Success Response (200)
- **dependencies** (array) - List of dependencies

#### Response Example
{
  "dependencies": []
}
```

--------------------------------

### Example usage of OpenService for creating an app and authenticating

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/open.md

This example shows how to obtain the OpenService instance via TypeDI, create a CLI app with two scopes, mint a token, and handle client rotation. It demonstrates that authToken does not throw on bad credentials but returns an object with code 400, and that resetSecret invalidates all existing tokens.

```typescript
import { Container } from 'typedi';
import OpenService from '../services/open';

const openService = Container.get(OpenService);

// create a CLI app with two scopes
const app = await openService.create({
  name: 'my-agent',
  scopes: ['crons', 'subscriptions'],
});
console.log(app.client_id, app.client_secret);

// mint a token (same as GET /open/auth/token)
const auth = await openService.authToken({
  client_id: app.client_id,
  client_secret: app.client_secret,
});
console.log(auth.data.token, auth.data.token_type);

// handle client rotation: if the auth fails, reset the secret & clear tokens
try {
  await openService.authToken({ client_id: 'x', client_secret: 'y' });
} catch (e) {
  // authToken does not throw on bad credentials; it returns code 400
}
const bad = await openService.authToken({ client_id: 'x', client_secret: 'y' });
if (bad.code === 400) {
  await openService.resetSecret(app.id!); // invalidates all existing tokens
}
```

--------------------------------

### readLogChunk usage example

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/process-tools.md

Example of reading a log file in chunks using readLogChunk. It starts at offset 0, iterates until the end, and includes a safety break to ensure forward progress.

```typescript
import { readLogChunk, MAX_LOG_CHUNK_BYTES } from '../shared/logReader';

const first = await readLogChunk('/data/log/demo/demo-1.log', { offset: 0, limit: 4096 });
let cursor = first.nextOffset;
while (cursor < first.total) {
  const next = await readLogChunk('/data/log/demo/demo-1.log', { offset: cursor, limit: 4096 });
  console.log(next.content);
  if (next.nextOffset <= cursor) break;   // safety: ensure forward progress
  cursor = next.nextOffset;
}
```

--------------------------------

### Build frontend with pnpm run build:front

Source: https://github.com/whyour/qinglong/blob/develop/docs/PROJECT_ARCHITECTURE.md

Generates the production frontend output, placed under static/dist.

```bash
pnpm run build:front
```

--------------------------------

### RetentionService usage example

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/retention.md

Shows how to obtain the service via TypeDI, build a cleanup request, preview the plan, and execute cleanup with confirmation.

```typescript
import { Container } from 'typedi';
import RetentionService from '../services/retention';

const retention = Container.get(RetentionService);

const request = {
  runningInstanceRetentionDays: 30,
  cronStatRetentionDays: 365,
  dependenceCacheTypes: ['node'],
  compactDatabase: true,
};
const plan = await retention.preview(request);
console.log(plan.runningInstances, plan.cronStats, plan.dependenceCacheBytes); // nothing deleted yet

const result = await retention.cleanup({ ...request, confirmation: 'CLEAN' });
console.log(result.deleted, result.compactedDatabase);
```

--------------------------------

### Usage example for SshKeyService

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/ssh-key.md

Example of using SshKeyService to add a per-host identity, add a global identity, and clean up. The example shows importing from 'typedi' and the service, and demonstrates that removeSSHKey errors are logged internally and swallowed.

```typescript
import { Container } from 'typedi';
import SshKeyService from '../services/sshKey';
import { Subscription } from '../data/subscription';

const ssh = Container.get(SshKeyService);

// per-host identity for a private repo (created automatically by subscriptions)
await ssh.addSSHKey('-----BEGIN OPENSSH PRIVATE KEY-----...', 'repo-a', 'github.com', '127.0.0.1:7890');

// global fallback identity
await ssh.addGlobalSSHKey('-----BEGIN OPENSSH PRIVATE KEY-----...', 'global');

// cleanup
try {
  await ssh.removeSSHKey('repo-a', 'github.com');
} catch (e) {
  // fs errors during cleanup are logged internally and swallowed
}
```

--------------------------------

### cronService.log usage example

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/cron.md

Example usage of cronService.log with offset, limit, and tail options. The next poll should use chunk.nextOffset.

```typescript
const chunk = await cronService.log(12, { offset: 0, limit: 1000, tail: true });
console.log(chunk.content, chunk.nextOffset, chunk.total); // next poll from chunk.nextOffset
```

--------------------------------

### Build and run internal CLI commands

Source: https://github.com/whyour/qinglong/blob/develop/cli/LOCAL.en.md

Install dependencies, build the CLI, and run help or task execution commands. Use on the actual panel host or inside its container; for Docker use docker exec with the selected absolute entry.

```sh
npm ci --prefix cli
npm run build:cli
node cli/dist/ql.js --help
node cli/dist/ql.js task exec --root /ql demo.js now
node cli/dist/ql.js reload --root /ql
```

--------------------------------

### parseCronSchedule usage example

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/cron-schedule.md

Example of importing and using parseCronSchedule with '@daily' and handling Huginn syntax errors. Outputs patterns and day counts.

```typescript
import { parseCronSchedule } from '../shared/cronSchedule';

const parsed = parseCronSchedule('@daily');        // or '0 0 0 * * *'
console.log(parsed.patterns);                      // ['0 0 0 * * *', '0 0 0 * * *']
console.log(parsed.dayCount, parsed.nthDay);       // 32, 0

try {
  parseCronSchedule('H 12 * * *');                 // Huginn syntax
} catch (e) {
  console.log((e as Error).message);               // 'Unsupported cron syntax'
}
```

--------------------------------

### Build backend with pnpm run build:back

Source: https://github.com/whyour/qinglong/blob/develop/docs/PROJECT_ARCHITECTURE.md

Generates the production-style backend output, placed under static/build.

```bash
pnpm run build:back
```

--------------------------------

### serveEnv function signature for /api/env.js

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/fs-utils.md

Serves GET /api/env.js with window.__ENV__QlBaseUrl=... etc. for the frontend, picking QlBaseUrl, DeployEnv, and QL_DIR only.

```typescript
export function serveEnv(_req: Request, res: Response)
```

--------------------------------

### Create task, subscription, app, env, and run cron via ql api

Source: https://github.com/whyour/qinglong/blob/develop/cli/README.en.md

Creates a task, subscription, application, environment variable, and runs a cron job using the ql CLI. Uses --data for JSON bodies, --query for query objects, --file for uploads, and --output for downloads. New commands support --timeout seconds. Downloads do not overwrite files. App secrets require --show-secrets.

```sh
ql task create --name demo --command 'task demo.js' --schedule '0 0 * * *' --json
ql subscription create --type public-repo --url https://example.com/repo.git --alias demo --schedule-type crontab --schedule '0 0 * * *' --json
ql app create --name agent --scopes crons,subscriptions --show-secrets --json
ql env create --data @envs.json --json
ql api request PUT /open/crons/run --data '[12,13]' --json
```

--------------------------------

### formatCommand for repositories and files

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/subscription.md

Builds the shell command for repository and file subscriptions. Repository commands use 'ql repo' with whitelist, blacklist, dependencies, branch, extensions, proxy, and cron flags. File commands use 'ql raw' with URL, proxy, and cron flags. Both include the SUB_ID environment variable.

```ts
`SUB_ID=${id} ql repo "${url}" "${whitelist}" "${blacklist}" "${dependences}" "${branch}" "${extensions}" "${proxy}" "${autoAddCron}" "${autoDelCron}"`
```

```ts
`SUB_ID=${id} ql raw "${url}" "${proxy}" "${autoAddCron}" "${autoDelCron}"`
```

--------------------------------

### DELETE /api/dependencies

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Uninstalls dependencies if installed.

```APIDOC
## DELETE /api/dependencies

### Description
Uninstalls dependencies if installed.

### Method
DELETE

### Endpoint
/api/dependencies

### Parameters
#### Request Body
- **id** (array of string) - Required - Dependency IDs

### Request Example
[
  "123",
  "456"
]

### Response
#### Success Response (200)
- **message** (string) - Success message

#### Response Example
{
  "message": "success"
}
```

--------------------------------

### HttpServerService methods: initialize, shutdown, getServer

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/server.md

Public API of HttpServerService. initialize binds to config.bindHost (default '::') with fallback to 0.0.0.0, using exclusive: process.env.QL_HTTP_SHARED_LISTEN !== 'true'. Records http_service_start/http_service_stop metrics and throws the last bind error if all hosts fail.

```typescript
async initialize(expressApp: express.Application, port: number): Promise<Server>
async shutdown(): Promise<void>
getServer(): Server | undefined
```

--------------------------------

### GET /api/system

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Retrieves system information.

```APIDOC
## GET /api/system

### Description
Retrieves system information.

### Method
GET

### Endpoint
/api/system

### Response
#### Success Response (200)
- **isInitialized** (boolean) - Whether system is initialized
- **version** (string) - Version
- **publishTime** (string) - Publish time
- **branch** (string) - Branch
- **changeLog** (string) - Change log
- **changeLogLink** (string) - Change log link

#### Response Example
{
  "isInitialized": true,
  "version": "1.0.0",
  "publishTime": "2023-01-01",
  "branch": "master",
  "changeLog": "...",
  "changeLogLink": "https://example.com"
}
```

--------------------------------

### POST /system/storage-retention/preview

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/api-reference/retention.md

Performs a dry run of the retention cleanup, computing counts of running instances and cron stats to be deleted, dependency cache sizes, and whether database compaction would be needed. Returns a preview plan without deleting anything.

```APIDOC
## [POST] /system/storage-retention/preview

### Description
Performs a dry run of the retention cleanup. It computes the number of running instances and cron stats that would be deleted, the byte sizes of dependency caches, and whether database compaction would be needed. No data is deleted.

### Method
POST

### Endpoint
/system/storage-retention/preview

### Parameters
#### Request Body
- **runningInstanceRetentionDays** (integer) - Required - Retention days for running instances. Must be between 0 and 3650.
- **cronStatRetentionDays** (integer) - Required - Retention days for cron statistics. Must be between 0 and 3650.
- **dependenceCacheTypes** (array of string) - Optional - Types of dependency caches to include. Allowed values: 'node', 'python3'. Default: [].
- **compactDatabase** (boolean) - Optional - Whether to compact the database. Default: false.

### Request Example
{
  "runningInstanceRetentionDays": 30,
  "cronStatRetentionDays": 365,
  "dependenceCacheTypes": ["node"],
  "compactDatabase": true
}

### Response
#### Success Response (200)
- **policy** (object) - The normalized retention policy.
- **runningInstances** (integer) - Number of running instances that would be deleted.
- **cronStats** (integer) - Number of cron stats that would be deleted.
- **dependenceCaches** (array) - Array of objects with type and byte size for each dependency cache.
- **dependenceCacheBytes** (integer) - Total bytes of dependency caches.
- **compactDatabase** (boolean) - Whether database compaction would be performed.

#### Response Example
{
  "policy": {
    "runningInstanceRetentionDays": 30,
    "cronStatRetentionDays": 365
  },
  "runningInstances": 10,
  "cronStats": 100,
  "dependenceCaches": [
    {
      "type": "node",
      "bytes": 1024
    }
  ],
  "dependenceCacheBytes": 1024,
  "compactDatabase": true
}
```

--------------------------------

### PUT /api/system/config/linux-mirror

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Rewrites apt/apk sources.

```APIDOC
## PUT /api/system/config/linux-mirror

### Description
Rewrites apt/apk sources.

### Method
PUT

### Endpoint
/api/system/config/linux-mirror

### Parameters
#### Request Body
- **linuxMirror** (string) - Required - Linux mirror URL

### Request Example
{
  "linuxMirror": "http://archive.ubuntu.com/ubuntu"
}

### Response
#### Success Response (200)
- **message** (string) - Success message

#### Response Example
{
  "message": "success"
}
```

--------------------------------

### GET /api/dashboard/failures

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Retrieves a list of failed tasks.

```APIDOC
## GET /api/dashboard/failures

### Description
Retrieves a list of failed tasks.

### Method
GET

### Endpoint
/api/dashboard/failures

### Response
#### Success Response (200)
- **code** (number) - Status code.
- **data** (array) - List of failed tasks.
  - **id** (number) - Task ID.
  - **name** (string) - Task name.
  - **command** (string) - Command.
  - **failCount** (number) - Failure count.
  - **deleted** (boolean) - Whether deleted.

#### Response Example
{
  "code": 200,
  "data": []
}
```

--------------------------------

### CLI 构建与验证命令

Source: https://github.com/whyour/qinglong/blob/develop/cli/README.md

在 cli 目录下安装依赖、运行类型检查、测试和包验证。

```sh
npm ci --prefix cli
npm run check:cli
npm run test:cli
node cli/scripts/verify-package.cjs
```

--------------------------------

### GET /api/dashboard/successes

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Retrieves a list of successful tasks.

```APIDOC
## GET /api/dashboard/successes

### Description
Retrieves a list of successful tasks.

### Method
GET

### Endpoint
/api/dashboard/successes

### Response
#### Success Response (200)
- **code** (number) - Status code.
- **data** (array) - List of successful tasks.
  - **id** (number) - Task ID.
  - **name** (string) - Task name.
  - **command** (string) - Command.
  - **successCount** (number) - Success count.
  - **deleted** (boolean) - Whether deleted.

#### Response Example
{
  "code": 200,
  "data": []
}
```

--------------------------------

### Build and run Debian CLI test image

Source: https://github.com/whyour/qinglong/blob/develop/cli/test/linux/README.md

Build and run the Debian-based CLI test image. The runtime mounts the cli, shell, and back/api directories read-only, uses no external network, and does not replace installed ql/task commands.

```sh
docker build -t qinglong-cli-test:node22-debian cli/test/linux
docker run --rm --network none \
  --mount type=bind,src="$(pwd)/cli",dst=/workspace/cli,readonly \
  --mount type=bind,src="$(pwd)/shell",dst=/workspace/shell,readonly \
  --mount type=bind,src="$(pwd)/back/api",dst=/workspace/back/api,readonly \
  --workdir /workspace qinglong-cli-test:node22-debian
```

--------------------------------

### GET /api/dashboard/overview

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Retrieves dashboard overview statistics.

```APIDOC
## GET /api/dashboard/overview

### Description
Retrieves dashboard overview statistics.

### Method
GET

### Endpoint
/api/dashboard/overview

### Response
#### Success Response (200)
- **code** (number) - Status code.
- **data** (object) - Overview statistics.
  - **total** (number) - Total tasks.
  - **enabled** (number) - Enabled tasks.
  - **disabled** (number) - Disabled tasks.
  - **todayRuns** (number) - Today's runs.
  - **todaySuccess** (number) - Today's successes.
  - **todayFail** (number) - Today's failures.
  - **successRate** (number) - Success rate.
  - **avgTime** (number) - Average time.

#### Response Example
{
  "code": 200,
  "data": {
    "total": 10,
    "enabled": 5,
    "disabled": 5,
    "todayRuns": 3,
    "todaySuccess": 2,
    "todayFail": 1,
    "successRate": 0.67,
    "avgTime": 10
  }
}
```

--------------------------------

### GET /api/system/client-ip/config

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Retrieves client IP configuration.

```APIDOC
## GET /api/system/client-ip/config

### Description
Retrieves client IP configuration.

### Method
GET

### Endpoint
/api/system/client-ip/config

### Response
#### Success Response (200)
- **trustProxy** (boolean) - Whether to trust proxy
- **source** (string) - Source
- **editable** (boolean) - Whether editable

#### Response Example
{
  "trustProxy": true,
  "source": "header",
  "editable": true
}
```

--------------------------------

### GET /api/configs/detail

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Retrieves the content of a configuration file. Files under 'sample/' are fetched from GitLab raw.

```APIDOC
## GET /api/configs/detail

### Description
Retrieves the content of a configuration file. Files under 'sample/' are fetched from GitLab raw.

### Method
GET

### Endpoint
/api/configs/detail

### Parameters
#### Query Parameters
- **path** (string) - Required - The path of the configuration file.

### Response
#### Success Response (200)
- **content** (string) - The file content.

#### Response Example
```
# content of the file
```
```

--------------------------------

### GET /api/system/log

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Retrieves streamed daily logs.

```APIDOC
## GET /api/system/log

### Description
Retrieves streamed daily logs.

### Method
GET

### Endpoint
/api/system/log

### Parameters
#### Query Parameters
- **startTime** (string) - Optional - Start time
- **endTime** (string) - Optional - End time
- **limit** (number) - Optional - Limit

### Response
#### Success Response (200)
- **logs** (array) - Log entries

#### Response Example
{
  "logs": []
}
```

--------------------------------

### View logs and run maintenance commands

Source: https://github.com/whyour/qinglong/blob/develop/deploy/kubernetes/README.md

Shows how to stream logs and execute the ql check and ql update commands inside the Qinglong pod for maintenance.

```bash
kubectl -n qinglong logs -f statefulset/qinglong
kubectl -n qinglong exec -it statefulset/qinglong -- ql check
kubectl -n qinglong exec -it statefulset/qinglong -- ql update
```

--------------------------------

### GET /api/dependencies/:id

Source: https://github.com/whyour/qinglong/blob/develop/_autodocs/endpoints.md

Retrieves a dependency by ID.

```APIDOC
## GET /api/dependencies/:id

### Description
Retrieves a dependency by ID.

### Method
GET

### Endpoint
/api/dependencies/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - Dependency ID

### Response
#### Success Response (200)
- **dependency** (object) - Dependency details

#### Response Example
{
  "dependency": {}
}
```
Tokens:
Raw