Skip to content

fix(infra): relocate wizard password file under OCTOP_HOME with legacy fallback (#2171) - #2174

Merged
jubaoliang merged 2 commits into
TencentCloud:developfrom
legend91019:fix/wizard-password-relocate-octop-home
Oct 19, 2026
Merged

jubaoliang merged 2 commits into
TencentCloud:developfrom
legend91019:fix/wizard-password-relocate-octop-home

Conversation

@legend91019

Copy link
Copy Markdown
Contributor

Summary

Fixes #2171.

Problem

When OCTOP_HOME is set to relocate the Octop data directory (e.g. to a persistent mount, portable drive, or green install), the first-run setup wizard password file octop-login.txt was still hardcoded to the OS user home directory (~/octop-login.txt / %USERPROFILE%).

Root causes:

  1. src/octop/infra/server.py:712 hardcoded wizard_home = Path.home(), ignoring self.paths.root (OCTOP_HOME).
  2. src/octop/api/routers/setup.py:237, :248, and :336 hardcoded Path.home() / WIZARD_FILE_NAME and _wizard.read_password(Path.home()).
  3. In containerized environments or service accounts with read-only home directories, writing to Path.home() failed or wrote outside the monitored data volume, requiring entrypoint hacks (docker/docker-entrypoint.sh). Furthermore, .env.example:18 already documented ~/.octop/octop-login.txt, creating a documentation and runtime mismatch.

Solution

  1. Path Layout: Added wizard_password_file property to PathLayout pointing to <root>/octop-login.txt.
  2. Password Lifecycle with Migration & Fallback:
    • password_file.resolve_password_path(home, legacy_home=None): Resolves primary <home>/octop-login.txt. If absent, falls back to legacy <legacy_home>/octop-login.txt (defaulting to Path.home()).
    • password_file.ensure_password(home, legacy_home=None): When creating the password in a new <home>, if a legacy password file already exists, reuses and synchronizes the legacy secret to the primary location to avoid generating conflicting credentials.
    • password_file.read_password(home, legacy_home=None): Reads from primary or legacy location seamlessly.
    • password_file.boot_self_heal(home, user_count, legacy_home=None): Reconciles the secret at server boot using the resolved root and legacy fallback.
  3. Server & Setup Router:
    • Updated Server._emit_wizard_password to use self.paths.root and dynamically display the resolved file path in the startup banner.
    • Updated /api/setup/status and /api/setup/verify-password to resolve and verify against server.paths.root with legacy fallback.
  4. Tests:
    • Added unit test in tests/unit/test_paths.py verifying PathLayout.wizard_password_file.
    • Added unit tests in tests/unit/test_wizard_password.py covering primary preference, legacy fallback, and boot migration.
    • Added integration test test_wizard_password_relocated_to_octop_home in tests/integration/test_setup_wizard.py verifying that relocated homes create the file inside the data root and never pollute Path.home().
    • Updated integration test assertions across test_setup_wizard.py, test_setup_bootstrap.py, test_postgresql_control_plane.py, and test_setup_database.py.

Target branch

  • Base is develop (feature / fix — default)
  • Base is main (release/* or hotfix/* only)

Type of change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation
  • Refactor / chore
  • Release / hotfix

Test plan

  • Unit & integration tests pass:
    • uv run pytest tests/unit/test_wizard_password.py tests/unit/test_paths.py (23 passed, 1 skipped)
    • uv run pytest tests/integration/test_setup_bootstrap.py (9 passed)
    • uv run pytest tests/integration/test_setup_wizard.py (28 passed)
    • uv run pytest tests/integration/test_setup_database.py (4 passed)
  • Typecheck & lint pass:
    • uv run ruff check src/octop/infra/utils/paths.py src/octop/infra/setup/password_file.py src/octop/infra/server.py src/octop/api/routers/setup.py
    • uv run ruff format --check
    • uv run mypy src/octop/infra/utils/paths.py src/octop/infra/setup/password_file.py src/octop/infra/server.py src/octop/api/routers/setup.py
  • Added/updated tests

Checklist

  • Updated CHANGELOG.md (if user-facing)
  • README / docs updated (if needed)

@TrueFurina

Copy link
Copy Markdown

Thanks for the fix — and for updating the integration tests, which is exactly what #2171 flagged as the blocker. The legacy fallback also reads correctly: the existing password is reused instead of generating a conflicting secret, and the copy is an atomic O_CREAT|O_EXCL write with 0o600. Base branch develop also matches the contribution rules.

One thing before this can land: CHANGELOG.md is not updated. The convention for backend/infra fixes is an entry under ## [Unreleased] → ### 修复 — see #2178 for the format (one bullet per behaviour change, issue number in parentheses). Suggested entry:

- `OCTOP_HOME` 迁移数据目录后,首次配置向导密码文件随之写入 `<OCTOP_HOME>/octop-login.txt`;旧位置 `~/octop-login.txt` 自动继承,不再生成冲突密码(#2171)

(We opened #2171 — happy to re-review once the CHANGELOG entry is in.)

@legend91019

Copy link
Copy Markdown
Contributor Author

@TrueFurina Thanks for the review and reminder! I have added the entry to CHANGELOG.md under ## [Unreleased] -> ### 修复 in commit 1271af24:

- `OCTOP_HOME` 迁移数据目录后,首次配置向导密码文件随之写入 `<OCTOP_HOME>/octop-login.txt`;旧位置 `~/octop-login.txt` 自动继承,不再生成冲突密码(#2171)

…y fallback

Derive the wizard password location from PathLayout root (OCTOP_HOME)
instead of hardcoding Path.home(). When OCTOP_HOME is relocated, the
password file is created and resolved from <OCTOP_HOME>/octop-login.txt.

To preserve complete backward compatibility for existing installations,
resolve_password_path, ensure_password, and read_password maintain a
fallback to legacy ~/octop-login.txt, migrating and synchronizing the
secret on boot when upgrading so no duplicate secrets are generated.

Closes TencentCloud#2171
@legend91019
legend91019 force-pushed the fix/wizard-password-relocate-octop-home branch from 1271af2 to 5ecf725 Compare October 19, 2026 03:04
@jubaoliang

Copy link
Copy Markdown
Collaborator

Maintainer triage note

Looks merge-ready for #2171 (OCTOP_HOME wizard password + legacy fallback). CI was already progressing; please keep Windows CI green. Optional follow-up after merge: simplify the Docker entrypoint $HOME/octop-login.txt symlink now that the server reads PathLayout.root.

@jubaoliang
jubaoliang merged commit 66e4cfc into TencentCloud:develop Oct 19, 2026
3 checks passed
TrueFurina added a commit to TrueFurina/Octop that referenced this pull request Oct 24, 2026
…Cloud#2174

TencentCloud#2174 (merged 2026-10-19) relocated the first-run wizard password to
<OCTOP_HOME>/octop-login.txt, honoring a pre-existing ~/octop-login.txt
as a legacy fallback.

The note added in this PR predates that merge and asserts the opposite
("OCTOP_HOME does not move it"), which would contradict .env.example as
corrected in TencentCloud#2369 once both land. Align this section with the merged
behavior so the two documents agree.
TrueFurina added a commit to TrueFurina/Octop that referenced this pull request Nov 2, 2026
- TencentCloud#2495 fix(oauth): preserve existing query params on authorization_endpoint (TencentCloud#2391)
- TencentCloud#2529 fix(execute_env): fold admin env into local_shell backend (close TencentCloud#179)
- TencentCloud#2543 [CLOSED BY AUTHOR] accidental empty blob commit - re-opening with fix
- TencentCloud#2570 fix(core): guard POSIX-only os.chmod/os.umask on Windows (TencentCloud#2370)
- TencentCloud#2571 fix(tls): guard POSIX-only os.chmod on Windows (TencentCloud#2370)
- TencentCloud#2572 fix(core): guard final POSIX-only os.chmod call sites (TencentCloud#2370)
- TencentCloud#2573 fix(experts): guard POSIX-only os.chmod in skill scripts (TencentCloud#2370)
- TencentCloud#2575 fix(agents): reuse _token_int in _usage_has_segments for safe coercion
- TencentCloud#2580 fix(shell): guard bare int() in shell_ws resize handler
- TencentCloud#2605 fix(xlsx): suppress PermissionError during soffice shim temp cleanup
- TencentCloud#2648 fix(security): prevent path-traversal in tccli OAuth helper --profile
- TencentCloud#2665 fix(octop): guard credential marker reads and backup file read with OSError
- TencentCloud#2692 fix(cli): read shell rc file as UTF-8 when installing completion
- TencentCloud#2706 fix(security): write tool guard rules atomically so a torn save cannot disable the guard
- TencentCloud#2731 fix(gateway): keep TLS verification when sending the Feishu greeting
- TencentCloud#2596 fix(clinical): avoid TOCTOU in atomic_write temp cleanup
- TencentCloud#2597 fix(service): suppress OSError in _write_managed_file finally cleanup
- TencentCloud#2599 fix(skill-manager): use unlink(missing_ok=True) to close TOCTOU in restore
- TencentCloud#2600 fix(users): add missing_ok=True to avatar unlink in delete_profile_avatar
- TencentCloud#2601 fix(api): add missing_ok=True to daily-memory delete unlink
- TencentCloud#2604 fix(agently): add missing_ok=True to confirmation-file unlinks
- TencentCloud#2606 fix(ldap): narrow _safe_unbind suppress(Exception) to LDAPException
- TencentCloud#2607 fix(skills): narrow suppress(Exception) around proc.wait to specific errors
- TencentCloud#2635 fix(cli): narrow suppress(Exception) in _close_cli_session to OSError+RuntimeError
- TencentCloud#2636 fix(feishu): narrow suppress(Exception) in creator timeout finally to OSError
- TencentCloud#2637 fix(gateway): narrow suppress(Exception) in usage_record to OSError
- TencentCloud#2639 fix(terminal): narrow suppress(Exception) in agent-fallback lookup to OSError
- TencentCloud#2640 fix(backend): narrow suppress(Exception) in probe.py docker path to OSError+RuntimeError
- TencentCloud#2641 fix(browse): narrow _close_backend suppress(Exception) to OSError+RuntimeError
- TencentCloud#2643 fix(backup): add timeout=900 to pg_dump and pg_restore subprocess.run
- TencentCloud#2645 fix(pptx): add missing_ok=True to all bare unlink/rmdir in clean.py
- TencentCloud#2646 fix(soffice): add missing_ok=True to gcc shim temp-file cleanup in docx and pptx skills
- TencentCloud#2647 fix(composer): narrow suppress(Exception) in write_files adelete to OSError+RuntimeError
- TencentCloud#2652 Add encoding=utf-8 to pdf skill scripts and timeout to ollama pkill
- TencentCloud#2690 fix(backup): unlink symlinked/junctioned dirs during replace import
- TencentCloud#2693 fix(env): write ~/.octop/env atomically
- TencentCloud#2478 fix(cli): guard bundled import when --force clears site-packages (TencentCloud#2458)
- TencentCloud#2541 guard seed_bundled so init --force never wipes data then crashes (TencentCloud#2458)
- TencentCloud#2566 fix(cron): add in-process idempotency guard against duplicate deliveries (TencentCloud#2401)
- TencentCloud#2577 fix(config): guard bare int() on http_port and database port parsing
- TencentCloud#2578 fix(voice): guard bare int() on tencent voice_type coercion
- TencentCloud#2585 fix(cli): guard remaining bare asyncio.run() in skills.py and launch.py
- TencentCloud#2586 fix(utils): specify encoding=utf-8 on subprocess text=True calls
- TencentCloud#2588 fix(infra): add encoding=utf-8 to subprocess text=True in control
- TencentCloud#2593 fix(experts): add encoding=utf-8 to macro read_text calls
- TencentCloud#2653 office skills: add explicit encoding=utf-8 to open() in PDF and validator scripts
- TencentCloud#2654 patrol_server.py: add explicit encoding=utf-8 to JSONL file reader
- TencentCloud#2656 Guard Path.iterdir() with OSError in browser_media and skill_package_store
- TencentCloud#2661 fix(octop): guard glob/rglob with OSError in expert catalog discovery
- TencentCloud#2664 fix(octop): guard slim_control endpoint read with OSError and JSON parse errors
- TencentCloud#2170 docs: complete the ~/.octop layout tree and note the wizard password location
- TencentCloud#2369 docs: fix wizard password path in .env.example (post-TencentCloud#2174)
- TencentCloud#2480 fix(thread-artifacts): prefer tool result path over request args (TencentCloud#2464)
- TencentCloud#2484 Fix active-turn flag leak with TTL-based stale eviction (issue TencentCloud#2456)
- TencentCloud#2490 fix(cli): handle EXDEV when backup output crosses filesystems
- TencentCloud#2494 fix(grep_safety): search only target file path, not parent dir siblings (TencentCloud#2352)
- TencentCloud#2509 fix(sso): only treat same-origin opener as Octop SSO popup (TencentCloud#2347)
- TencentCloud#2519 fix(provider-probe): skip disabled models when picking default probe target (TencentCloud#2312)
- TencentCloud#2526 fix(knowledge): emit citations only for hits that made it into context (TencentCloud#1490)
- TencentCloud#2527 fix(hitl): isolate pending approvals by thread, not just session (TencentCloud#1897)
- TencentCloud#2539 fix(message_keys): group-chat sessions key by room not by sender (TencentCloud#2067)
- TencentCloud#2542 return 409 PROVIDER_NAME_TAKEN on duplicate provider creation (TencentCloud#1967)
- TencentCloud#2548 fix(skillhub): retry HTTP request on transient CDN IPv4 failure (TencentCloud#1819)
- TencentCloud#2562 fix(cron): preserve interval next_run_time across rebuilds (TencentCloud#2292)
- TencentCloud#2581 fix(gateway): use time.monotonic() for bot scan-poll deadline loop
- TencentCloud#2592 fix(core): make cleanup and datetime parsing resilient
- TencentCloud#2631 fix(users): add ignore_errors=True to checkpoint rmtree
- TencentCloud#2699 fix(media): serialize inbound attachment path allocation and upload
- TencentCloud#2714 fix(gateway): parse creator events from a text-mode subprocess pipe
- TencentCloud#2720 fix(preferences): keep bookmarks with upper-case URL scheme
TrueFurina added a commit to TrueFurina/Octop that referenced this pull request Nov 2, 2026
- TencentCloud#2495 fix(oauth): preserve existing query params on authorization_endpoint (TencentCloud#2391)
- TencentCloud#2529 fix(execute_env): fold admin env into local_shell backend (close TencentCloud#179)
- TencentCloud#2570 fix(core): guard POSIX-only os.chmod/os.umask on Windows (TencentCloud#2370)
- TencentCloud#2571 fix(tls): guard POSIX-only os.chmod on Windows (TencentCloud#2370)
- TencentCloud#2572 fix(core): guard final POSIX-only os.chmod call sites (TencentCloud#2370)
- TencentCloud#2573 fix(experts): guard POSIX-only os.chmod in skill scripts (TencentCloud#2370)
- TencentCloud#2575 fix(agents): reuse _token_int in _usage_has_segments for safe coercion
- TencentCloud#2580 fix(shell): guard bare int() in shell_ws resize handler
- TencentCloud#2605 fix(xlsx): suppress PermissionError during soffice shim temp cleanup
- TencentCloud#2648 fix(security): prevent path-traversal in tccli OAuth helper --profile
- TencentCloud#2665 fix(octop): guard credential marker reads and backup file read with OSError
- TencentCloud#2692 fix(cli): read shell rc file as UTF-8 when installing completion
- TencentCloud#2706 fix(security): write tool guard rules atomically so a torn save cannot disable the guard
- TencentCloud#2731 fix(gateway): keep TLS verification when sending the Feishu greeting
- TencentCloud#2596 fix(clinical): avoid TOCTOU in atomic_write temp cleanup
- TencentCloud#2597 fix(service): suppress OSError in _write_managed_file finally cleanup
- TencentCloud#2599 fix(skill-manager): use unlink(missing_ok=True) to close TOCTOU in restore
- TencentCloud#2600 fix(users): add missing_ok=True to avatar unlink in delete_profile_avatar
- TencentCloud#2601 fix(api): add missing_ok=True to daily-memory delete unlink
- TencentCloud#2604 fix(agently): add missing_ok=True to confirmation-file unlinks
- TencentCloud#2606 fix(ldap): narrow _safe_unbind suppress(Exception) to LDAPException
- TencentCloud#2607 fix(skills): narrow suppress(Exception) around proc.wait to specific errors
- TencentCloud#2635 fix(cli): narrow suppress(Exception) in _close_cli_session to OSError+RuntimeError
- TencentCloud#2636 fix(feishu): narrow suppress(Exception) in creator timeout finally to OSError
- TencentCloud#2637 fix(gateway): narrow suppress(Exception) in usage_record to OSError
- TencentCloud#2639 fix(terminal): narrow suppress(Exception) in agent-fallback lookup to OSError
- TencentCloud#2640 fix(backend): narrow suppress(Exception) in probe.py docker path to OSError+RuntimeError
- TencentCloud#2641 fix(browse): narrow _close_backend suppress(Exception) to OSError+RuntimeError
- TencentCloud#2643 fix(backup): add timeout=900 to pg_dump and pg_restore subprocess.run
- TencentCloud#2645 fix(pptx): add missing_ok=True to all bare unlink/rmdir in clean.py
- TencentCloud#2646 fix(soffice): add missing_ok=True to gcc shim temp-file cleanup in docx and pptx skills
- TencentCloud#2647 fix(composer): narrow suppress(Exception) in write_files adelete to OSError+RuntimeError
- TencentCloud#2652 Add encoding=utf-8 to pdf skill scripts and timeout to ollama pkill
- TencentCloud#2690 fix(backup): unlink symlinked/junctioned dirs during replace import
- TencentCloud#2693 fix(env): write ~/.octop/env atomically
- TencentCloud#2478 fix(cli): guard bundled import when --force clears site-packages (TencentCloud#2458)
- TencentCloud#2541 guard seed_bundled so init --force never wipes data then crashes (TencentCloud#2458)
- TencentCloud#2566 fix(cron): add in-process idempotency guard against duplicate deliveries (TencentCloud#2401)
- TencentCloud#2577 fix(config): guard bare int() on http_port and database port parsing
- TencentCloud#2578 fix(voice): guard bare int() on tencent voice_type coercion
- TencentCloud#2585 fix(cli): guard remaining bare asyncio.run() in skills.py and launch.py
- TencentCloud#2586 fix(utils): specify encoding=utf-8 on subprocess text=True calls
- TencentCloud#2588 fix(infra): add encoding=utf-8 to subprocess text=True in control
- TencentCloud#2593 fix(experts): add encoding=utf-8 to macro read_text calls
- TencentCloud#2653 office skills: add explicit encoding=utf-8 to open() in PDF and validator scripts
- TencentCloud#2654 patrol_server.py: add explicit encoding=utf-8 to JSONL file reader
- TencentCloud#2656 Guard Path.iterdir() with OSError in browser_media and skill_package_store
- TencentCloud#2661 fix(octop): guard glob/rglob with OSError in expert catalog discovery
- TencentCloud#2664 fix(octop): guard slim_control endpoint read with OSError and JSON parse errors
- TencentCloud#2170 docs: complete the ~/.octop layout tree and note the wizard password location
- TencentCloud#2369 docs: fix wizard password path in .env.example (post-TencentCloud#2174)
- TencentCloud#2480 fix(thread-artifacts): prefer tool result path over request args (TencentCloud#2464)
- TencentCloud#2484 Fix active-turn flag leak with TTL-based stale eviction (issue TencentCloud#2456)
- TencentCloud#2490 fix(cli): handle EXDEV when backup output crosses filesystems
- TencentCloud#2494 fix(grep_safety): search only target file path, not parent dir siblings (TencentCloud#2352)
- TencentCloud#2509 fix(sso): only treat same-origin opener as Octop SSO popup (TencentCloud#2347)
- TencentCloud#2519 fix(provider-probe): skip disabled models when picking default probe target (TencentCloud#2312)
- TencentCloud#2522 fix(search-probe): make Kimi probe model configurable via env (TencentCloud#1926)
- TencentCloud#2526 fix(knowledge): emit citations only for hits that made it into context (TencentCloud#1490)
- TencentCloud#2527 fix(hitl): isolate pending approvals by thread, not just session (TencentCloud#1897)
- TencentCloud#2539 fix(message_keys): group-chat sessions key by room not by sender (TencentCloud#2067)
- TencentCloud#2542 return 409 PROVIDER_NAME_TAKEN on duplicate provider creation (TencentCloud#1967)
- TencentCloud#2548 fix(skillhub): retry HTTP request on transient CDN IPv4 failure (TencentCloud#1819)
- TencentCloud#2562 fix(cron): preserve interval next_run_time across rebuilds (TencentCloud#2292)
- TencentCloud#2581 fix(gateway): use time.monotonic() for bot scan-poll deadline loop
- TencentCloud#2592 fix(core): make cleanup and datetime parsing resilient
- TencentCloud#2631 fix(users): add ignore_errors=True to checkpoint rmtree
- TencentCloud#2699 fix(media): serialize inbound attachment path allocation and upload
- TencentCloud#2714 fix(gateway): parse creator events from a text-mode subprocess pipe
- TencentCloud#2720 fix(preferences): keep bookmarks with upper-case URL scheme
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.

3 participants