Investigate race condition in ql command availability - pending resolution

[Copilot]

This PR initially reverted proposed changes after discovering that the backend already handles symlink creation for the ql command. However, further investigation revealed a race condition that causes the reported issue.

Investigation

The ql command referenced in docker-entrypoint.sh (lines 45, 50) is created by the backend code in back/loaders/deps.ts, but there's a timing issue:

The linkCommandToDir() function in the backend:

• Creates the $HOME/bin directory
• Links shell/update.sh → $HOME/bin/ql
• Links shell/task.sh → $HOME/bin/task

This function is called automatically when the Node.js application starts via linkDeps() in back/loaders/app.ts.

Race Condition Identified

The docker-entrypoint.sh script has a race condition:

1. Line 41: reload_pm2 starts the Node.js backend asynchronously in the background
2. Lines 45, 50: Immediately try to use ql command without waiting for backend initialization
3. Backend: The linkCommandToDir() function hasn't run yet, so symlinks don't exist
4. Result: "ql: command not found" error

The entrypoint script attempts to use the ql command before the backend has created the necessary symlinks, causing the user-reported issue.

Changes Made

• Reverted docker/docker-entrypoint.sh: Removed initially proposed symlink creation code
• Removed shell/ql.sh: Deleted initially proposed wrapper script

Root Cause Analysis

The original issue ("ql: command not found") reported by users is caused by a timing/race condition:

• The docker-entrypoint.sh script uses ql commands before the backend has finished initializing and creating the symlinks
• The backend creates symlinks asynchronously, but the entrypoint doesn't wait for this to complete

Status

Awaiting maintainer decision on resolution approach:

• Option 1: Create symlinks in docker-entrypoint.sh before use (original proposed fix)
• Option 2: Add wait mechanism for backend initialization
• Option 3: Alternative solution suggested by maintainer

Original prompt

---

This section details on the original issue you should resolve

<issue_title>ql: command not found</issue_title>
<issue_description>### Qinglong version

v2.20.1

Steps to reproduce

docker 安装后 运行ql指令

What is expected?

如何安装ql

What is actually happening?

ql: command not found

System Info

ql: command not found

Any additional comments?

也find不到ql.sh等脚本</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes ql: command not found #2891

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
qinglong	Ready	Preview, Comment	Dec 30, 2025 5:02pm
qinglong-back	Ready	Preview, Comment	Dec 30, 2025 5:02pm

[whyour]

@copilot linkCommandToDir 不是处理了吗

[Copilot]

@copilot linkCommandToDir 不是处理了吗

You're right! I found that linkCommandToDir in back/loaders/deps.ts already creates the symlinks (update.sh → ql and task.sh → task) when the backend starts. I've reverted my changes in commit 8d5e485.

The symlinks are created automatically by the backend's linkDeps() function, so the shell/ql.sh wrapper and docker-entrypoint.sh modifications were unnecessary.

[whyour]

@copilot linkCommandToDir 不是处理了吗

You're right! I found that linkCommandToDir in back/loaders/deps.ts already creates the symlinks (update.sh → ql and task.sh → task) when the backend starts. I've reverted my changes in commit 8d5e485.

The symlinks are created automatically by the backend's linkDeps() function, so the shell/ql.sh wrapper and docker-entrypoint.sh modifications were unnecessary.

那实际上为什么 ql 命令

[Copilot]

@copilot linkCommandToDir 不是处理了吗

You're right! I found that linkCommandToDir in back/loaders/deps.ts already creates the symlinks (update.sh → ql and task.sh → `ta...

实际上存在时序问题：

docker-entrypoint.sh 在第 45、50 行使用 ql 命令时，后端还未启动完成创建软链接。执行顺序：

1. 第 41 行：reload_pm2 在后台启动 Node.js
2. 第 45、50 行：立即尝试使用 ql 命令
3. 后端才初始化并执行 linkCommandToDir()

所以用户会遇到 "ql: command not found"。

需要在 docker-entrypoint.sh 中提前创建软链接，或者等待后端启动完成。我应该恢复之前的修改吗？