Skip to content

docs: 完善宝塔面板部署教程#105

Open
lcq225 wants to merge 2 commits intoQuantumNous:mainfrom
lcq225:docs/improve-bt-installation-guide
Open

docs: 完善宝塔面板部署教程#105
lcq225 wants to merge 2 commits intoQuantumNous:mainfrom
lcq225:docs/improve-bt-installation-guide

Conversation

@lcq225
Copy link
Copy Markdown

@lcq225 lcq225 commented Mar 22, 2026

📝 变更描述

完善 content/docs/zh/installation/deployment-methods/bt-docker-installation.mdx

新增内容

  • Docker Compose 安装方式 - 适合需要更多自定义配置的场景
  • 环境变量详细说明 - SESSION_SECRET、CRYPTO_SECRET、SQL_DSN、REDIS_CONN_STRING
  • 密钥生成命令 - openssl 和 Linux 命令两种方式
  • 版本更新方法 - Docker Compose 和宝塔容器管理两种方式
  • 相关链接 - 环境变量配置、Docker Compose 部署、常见问题、GitHub 仓库

优化内容

  • 使用表格展示前置要求
  • 使用表格展示环境变量说明
  • 优化文档结构(步骤一/二/三)
  • 保留原有 Callout 组件

🔗 相关

✅ 检查项

  • 文档格式符合项目规范(MDX)
  • 保留原有组件(Callout)
  • 内容基于官方文档和实际使用经验编写

Summary by CodeRabbit

  • Documentation
    • Reorganized installation guides into clear Step 1/2/3 workflows across deployments (BT, 1Panel, custom image).
    • Added Docker Compose as an alternative deployment method with example configuration and startup commands.
    • Introduced a dedicated environment-variables section (required/conditional/optional) and random-secret generation guidance.
    • Expanded access, troubleshooting and FAQ content (port access, session invalidation, persistence, upgrade procedures) and updated related links.

@vercel
Copy link
Copy Markdown

vercel bot commented Mar 22, 2026

@lcq225 is attempting to deploy a commit to the quantumnous Team on Vercel.

A member of the Team first needs to authorize it.

@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Mar 22, 2026

Walkthrough

Reorganized several deployment docs into step-based guides, added Docker Compose as a new deployment method, introduced a dedicated environment-variables section (notably SESSION_SECRET and CRYPTO_SECRET), adjusted install flows and troubleshooting, and synchronized changes across English, Chinese, and Japanese pages.

Changes

Cohort / File(s) Summary
BT Docker docs (zh/en/ja)
content/docs/zh/installation/deployment-methods/bt-docker-installation.mdx, content/docs/en/installation/deployment-methods/bt-docker-installation.mdx, content/docs/ja/installation/deployment-methods/bt-docker-installation.mdx
Rewrote structure to numbered steps; added Docker Compose method with example docker-compose.yml; required/conditional env vars added (SESSION_SECRET, CRYPTO_SECRET); updated install UI wording and post-install access instructions; replaced old FAQs with troubleshooting entries and related links.
1Panel deployment docs (zh/en/ja)
content/docs/zh/installation/deployment-methods/1panel-installation.mdx, content/docs/en/installation/deployment-methods/1panel-installation.mdx, content/docs/ja/installation/deployment-methods/1panel-installation.mdx
Converted linear install flow to multi-step tutorial (Prereqs + Step 1–4); added environment variable configuration step with required/conditional fields and secret-generation commands; expanded Access/Initialization and Common Issues; appended Related Links.
Cross-language consistency
content/docs/*/installation/deployment-methods/* (localized docs above)
Harmonized wording, added environment-variables section and secret generation commands, normalized formatting and trailing newline presence.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I nibble docs with careful paws,
Steps and secrets in tidy claws,
Compose sings containers in line,
Ports and volumes all align.
Hop — deploy, and it will shine! 🥕

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately describes the main change: improving/enhancing the Baota panel (宝塔面板) deployment tutorial documentation, which is the primary focus across multiple language versions.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Tip

You can get early access to new features in CodeRabbit.

Enable the early_access setting to enable early access features such as new models, tools, and more.

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
content/docs/zh/installation/deployment-methods/bt-docker-installation.mdx (1)

95-102: 小节标题与表格内容不一致。

Line 95 写“必要环境变量”,但 Line 101-102 包含可选项,建议改成“环境变量一览(含必填与可选)”或拆成两个表,避免误解。

✏️ 建议修改
-### 必要环境变量
+### 环境变量一览(含必填与可选)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@content/docs/zh/installation/deployment-methods/bt-docker-installation.mdx`
around lines 95 - 102, Heading "必要环境变量" is inconsistent with the table that
includes optional items; update the heading or split the table. Either rename
the heading to "环境变量一览(含必填与可选)" to reflect both required and optional entries,
or split the table into two titled tables like "必填环境变量" and "可选环境变量" and move
`SESSION_SECRET`/`CRYPTO_SECRET`/`SQL_DSN`/`REDIS_CONN_STRING` into the
appropriate table; ensure the heading(s) and table captions match the content.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@content/docs/zh/installation/deployment-methods/bt-docker-installation.mdx`:
- Around line 90-91: 在“环境变量”项中不要只写“根据需要添加”:将 SESSION_SECRET
明确标注为必填环境变量并在该节(环境变量/方法三)补充一句说明:“必须设置
SESSION_SECRET,否则会导致部署后会话失效(参见后文会话相关错误场景)”,以确保用户在使用方法三(bt-docker
安装)时不会遗漏该变量;定位修改点为当前文档中“环境变量”小节并替换原文“根据需要添加”为包含 SESSION_SECRET 必填说明。

---

Nitpick comments:
In `@content/docs/zh/installation/deployment-methods/bt-docker-installation.mdx`:
- Around line 95-102: Heading "必要环境变量" is inconsistent with the table that
includes optional items; update the heading or split the table. Either rename
the heading to "环境变量一览(含必填与可选)" to reflect both required and optional entries,
or split the table into two titled tables like "必填环境变量" and "可选环境变量" and move
`SESSION_SECRET`/`CRYPTO_SECRET`/`SQL_DSN`/`REDIS_CONN_STRING` into the
appropriate table; ensure the heading(s) and table captions match the content.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e459ec58-3f29-4d8b-be29-83f6affc2fa5

📥 Commits

Reviewing files that changed from the base of the PR and between 1e4dec6 and 221581c.

📒 Files selected for processing (1)
  • content/docs/zh/installation/deployment-methods/bt-docker-installation.mdx

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (4)
content/docs/ja/installation/deployment-methods/bt-docker-installation.mdx (2)

51-72: Same Docker Compose modernization applies here.

Same optional suggestion as the English version: the version key can be omitted, and docker compose (with space) is the modern command.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@content/docs/ja/installation/deployment-methods/bt-docker-installation.mdx`
around lines 51 - 72, Remove the obsolete top-level version key from the Docker
Compose snippet and update the docs text to recommend the modern CLI;
specifically adjust the YAML that defines the services/new-api (image,
container_name, restart, ports, volumes, environment including SESSION_SECRET
and TZ) so it omits the version: '3' line, and change the command example under
the SSH instructions from docker-compose up -d to the modern docker compose up
-d while keeping the same directory change (cd /www/wwwroot/new-api) and notes
about SESSION_SECRET.

143-151: Update commands could also use modern syntax.

-docker-compose down && docker-compose up -d
+docker compose down && docker compose up -d
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@content/docs/ja/installation/deployment-methods/bt-docker-installation.mdx`
around lines 143 - 151, Replace legacy docker CLI usage with the modern docker
compose V2 syntax: change the explicit image pull and docker-compose commands to
compose-aware commands — e.g., replace "docker pull calciumion/new-api:latest"
with "docker compose pull <service-name>" or use "docker compose up -d
--pull=always <service-name>" and replace "docker-compose down && docker-compose
up -d" with "docker compose down && docker compose up -d" (or "docker compose
restart <service-name>" for a simple restart). Update the third line to suggest
using the Compose restart command ("docker compose restart <service-name>") or
the container-level "docker restart <container>" as appropriate, and ensure you
reference the service name from your compose file rather than a raw image name.
content/docs/en/installation/deployment-methods/bt-docker-installation.mdx (2)

51-72: Consider updating Docker Compose syntax to modern conventions.

The version: '3' key is deprecated in Docker Compose V2 and can be omitted. Additionally, the docker-compose command is the legacy standalone tool; the modern equivalent is docker compose (space, not hyphen) which is built into Docker CLI.

This is a minor suggestion as both approaches still work, but updating to modern conventions would future-proof the documentation.

📝 Suggested modernization
-```yaml
-version: '3'
-services:
+```yaml
+services:
   new-api:
     image: calciumion/new-api:latest
-docker-compose up -d
+docker compose up -d
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@content/docs/en/installation/deployment-methods/bt-docker-installation.mdx`
around lines 51 - 72, Remove the deprecated top-level "version: '3'" key from
the Compose YAML and ensure the file uses the modern Compose V2 structure with
"services:" as the root (the existing service name is new-api and should remain
under services); also update the documented CLI invocation from the legacy
"docker-compose up -d" to the modern built-in "docker compose up -d" in the
instructions that run the compose file.

143-151: Same Docker Compose modernization applies to update commands.

For consistency with the earlier suggestion:

📝 Suggested update
 # Restart with Docker Compose
-docker-compose down && docker-compose up -d
+docker compose down && docker compose up -d
 
 # Or restart container via Baota container management
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@content/docs/en/installation/deployment-methods/bt-docker-installation.mdx`
around lines 143 - 151, Replace the legacy docker-compose usage in the snippet
that contains "docker pull calciumion/new-api:latest" and "docker-compose down
&& docker-compose up -d" with the modern Docker Compose CLI: use "docker pull
calciumion/new-api:latest" (or "docker compose pull calciumion/new-api:latest")
and change "docker-compose down && docker-compose up -d" to "docker compose down
&& docker compose up -d" (or consider "docker compose pull && docker compose up
-d --build" if you want to ensure images are updated and containers rebuilt).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@content/docs/en/installation/deployment-methods/bt-docker-installation.mdx`:
- Around line 51-72: Remove the deprecated top-level "version: '3'" key from the
Compose YAML and ensure the file uses the modern Compose V2 structure with
"services:" as the root (the existing service name is new-api and should remain
under services); also update the documented CLI invocation from the legacy
"docker-compose up -d" to the modern built-in "docker compose up -d" in the
instructions that run the compose file.
- Around line 143-151: Replace the legacy docker-compose usage in the snippet
that contains "docker pull calciumion/new-api:latest" and "docker-compose down
&& docker-compose up -d" with the modern Docker Compose CLI: use "docker pull
calciumion/new-api:latest" (or "docker compose pull calciumion/new-api:latest")
and change "docker-compose down && docker-compose up -d" to "docker compose down
&& docker compose up -d" (or consider "docker compose pull && docker compose up
-d --build" if you want to ensure images are updated and containers rebuilt).

In `@content/docs/ja/installation/deployment-methods/bt-docker-installation.mdx`:
- Around line 51-72: Remove the obsolete top-level version key from the Docker
Compose snippet and update the docs text to recommend the modern CLI;
specifically adjust the YAML that defines the services/new-api (image,
container_name, restart, ports, volumes, environment including SESSION_SECRET
and TZ) so it omits the version: '3' line, and change the command example under
the SSH instructions from docker-compose up -d to the modern docker compose up
-d while keeping the same directory change (cd /www/wwwroot/new-api) and notes
about SESSION_SECRET.
- Around line 143-151: Replace legacy docker CLI usage with the modern docker
compose V2 syntax: change the explicit image pull and docker-compose commands to
compose-aware commands — e.g., replace "docker pull calciumion/new-api:latest"
with "docker compose pull <service-name>" or use "docker compose up -d
--pull=always <service-name>" and replace "docker-compose down && docker-compose
up -d" with "docker compose down && docker compose up -d" (or "docker compose
restart <service-name>" for a simple restart). Update the third line to suggest
using the Compose restart command ("docker compose restart <service-name>") or
the container-level "docker restart <container>" as appropriate, and ensure you
reference the service name from your compose file rather than a raw image name.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: baa6d8d0-2055-448c-a833-13f5780ef56b

📥 Commits

Reviewing files that changed from the base of the PR and between 221581c and bd6a4fd.

📒 Files selected for processing (5)
  • content/docs/en/installation/deployment-methods/1panel-installation.mdx
  • content/docs/en/installation/deployment-methods/bt-docker-installation.mdx
  • content/docs/ja/installation/deployment-methods/1panel-installation.mdx
  • content/docs/ja/installation/deployment-methods/bt-docker-installation.mdx
  • content/docs/zh/installation/deployment-methods/1panel-installation.mdx

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant