Repository navigation
FAQ
中文 · English
这一页把「第一次用最容易卡住的地方」按主题攒成问答。答案都来自仓库里的文档与代码，凡是本项目没有的能力，这里会直接说「没有」，不会含糊过去。
默认管理员账号是什么？
初始口令是 admin / admin123（部署时可以用 BASTION_ADMIN_PASSWORD 指定别的口令）。第一次登录会强制改密，不改完进不去。忘了管理员口令不用重装：在服务器上执行 python run.py --reset-admin，按提示输入新口令即可。
登录失败几次会被锁？
默认连续失败 5 次锁定 15 分钟（BASTION_LOGIN_MAX_FAILURES=5、BASTION_LOGIN_LOCK_MINUTES=15）。锁定期间正确的口令也会被拒，成功与失败登录都会写审计。等锁定期过去，或者由管理员重置口令。
支持 LDAP / SSO / 双因子吗？
目前没有。账号是堡垒机自己的本地账号，登录成功后签发 JWT（浏览器存在 localStorage.bastion_token，请求带 Authorization: Bearer <token>）；SSH 网关那边是口令或公钥认证。仓库里没有 LDAP / OIDC / SAML / TOTP 的实现，也没留相关开关，所以不要按「能接 AD」来规划。
「超级管理员」和普通管理员有什么区别？
内置四个角色：admin（权限数组 ["*"]）、ops（17 个权限码）、auditor（9 个）、viewer（4 个）。界面上显示成「超级管理员」的就是 admin 角色，它不受「访问授权」表限制，能看所有主机；普通管理员/运维的可见范围由授权逐条决定。日常干活别用超管账号。
支持哪些协议？
SSH（22 或自定义端口）、WinRM（5985 HTTP / 5986 HTTPS）、RDP（3389）。一台主机可以挂多个协议端点（host_protocols 表，唯一约束 (host_id, protocol)，即同一台机器每个协议最多一条端点）。
同一台 Windows 机器既要远程桌面又要命令行，要建两条主机吗？ 不用。建一条主机记录，在「协议入口」里多选「Windows（命令行 + 远程桌面）」，再分别填 WinRM 端口与 RDP 端口就行。历史遗留的同地址两条记录（比如早期按协议拆的）可以用主机行里的「合并」：账号、授权、协议端点都会搬到目标记录上，来源记录随后删除，会话历史是审计数据不会被改写。
Windows Server 2003 / XP 这类老系统能开远程桌面吗？
不能，这是能力边界不是配置问题：老系统的 RDP 只支持 TLS 1.0 与标准 RDP 安全层，本项目已把握手放宽到兼容模式、能把会话推进到目标机回数据，但浏览器里的 ironrdp-wasm 最终仍以 decode error 收场。结论就是这类系统请用 Windows 自带的「远程桌面连接」。主机级「RDP 安全层」设成「强制 SSL」能绕开 NLA，让失败原因和出路写在告警、会话结束原因与审计里。
怎么快速判断主机能不能连？
主机行里的「测试连接」，可以用 ?protocol=ssh|winrm|rdp 指定测哪个端点；SSH 会同时打印目标机与本机（堡垒机）的 SSH 版本，方便区分是版本协商问题还是账号/网络问题。
网页终端一直显示「连接中」怎么办？
十有八九是反向代理没透传 WebSocket：/socket.io/ 必须带上 Upgrade、Connection 头（Nginx 的写法见 Install-and-Deploy）。直连本机 127.0.0.1:5000 能连上、走域名连不上，基本就可以确定是这一条。
Windows 主机连不上怎么排查？
先看目标机有没有开 WinRM（Enable-PSRemoting -Force）、端口对不对（HTTP 5985 / HTTPS 5986，填 5986 会自动走 TLS）；再确认主机记录里的账号口令、WinRM 认证方式（默认 NTLM）与目标机一致。RDP 连不上则看端口与「RDP 安全层」，老系统按上一条。
WinRM 会话里为什么 more / pause / Read-Host 不能用，cd 却能保留？
WinRM 是每个命令在目标机上单独执行：进程内的环境变量、自定义变量不保留，但当前目录（cd）会保留。交互式程序（分页、等待输入）没有真实控制台，所以不支持；会话头部的三行提示就是说明这件事。
终端里怎么传文件？ Linux 主机用终端工具条上的「文件管理」（走 SFTP）；WinRM 没有 SFTP 通道，那一行不渲染「文件」按钮。文件操作走和终端一样的授权与策略。
关掉终端窗口，会话还在吗？ 不在。一个标签页一条会话，关窗口即结束（服务端会记结束原因）。远程桌面窗口被强行关掉时，录像会按服务端自动收口的那部分保存下来，不会整段丢。
审计记录能删吗？
文件操作记录支持删除（POST /api/audits/files/delete），删的时候本身也会留一条记录；命令记录、会话记录不提供「改内容」的入口，设计的重点是改得掉、查得出——每条都带哈希链。
怎么自己校验哈希链？
仓库里带离线校验脚本：在 bastion-backend/ 下执行 python tools/verify_audit_chain.py。判据很明确：链起步之前的空哈希行属于老库升级遗留，合法；链起步之后再出现空哈希行会被标成异常（把哈希清空也算「改哈希」）。
资产口令怎么存的？
加密存库（Fernet，密钥是 bastion-backend/instance/fernet.key），界面上不明文回显。远程桌面是个例外：CredSSP 需要把口令下发到浏览器，这一步会明确写一条 rdp_credential_reveal 审计。
密钥文件丢了会怎样？
secret.key 丢 → JWT 全部失效（所有人重新登录即可，不影响数据）；fernet.key 丢 → 已保存的资产口令无法解密，只能重新录入。所以备份必须把 instance/ 整个目录带上。
AI 用什么模型？要配什么？
需要在 bastion-backend/.env 里写 DEEPSEEK_API_KEY 再重启服务。没配置时 /api/ai/chat 返回 400 AI_NOT_CONFIGURED，页面也会提示「尚未配置 DEEPSEEK_API_KEY（写入 bastion-backend/.env 后重启服务）」。
AI 会自己把命令执行了吗？
敏感操作会停下来等管理员当场确认（审计里记 ai_tool_confirm），批准后才执行；用户说了什么、AI 回了什么、调了哪些工具、谁批的，全部可查（「审计中心 → AI 对话审计」）。
在网页终端里也能问 AI 吗？
能：会话里输入 /ask-ai <问题>，回答以流式输出打回终端，同一次操作同样进审计。
要单独装数据库吗？
不用。默认是 SQLite 单文件 bastion-backend/instance/bastion.db，没有外部数据库依赖。
默认端口有哪些？
后端 API + 前端托管 5000；SSH 网关 2222；前端开发服务器 8000（npm run dev）。生产建议用 Nginx 反代 5000，并记得透传 WebSocket。
改完前端代码怎么上线？
npm run build 生成 ant-design-pro/dist/，后端启动时会托管它。注意后端只在启动时检查 dist/index.html 是否存在：先起后端、后构建的话，页面会显示「未发现前端构建产物…仅提供 API」，重启一次后端就好。
运行环境要求？
后端 Python ≥ 3.11（开发用 3.13，依赖见 bastion-backend/requirements.txt）；前端 Node ≥ 22（ant-design-pro/package.json 的 engines.node 写的就是 ≥ 22，根 README 的「≥ 20」是更宽的旧口径，按 22 来最稳）。
备份和升级怎么做？
见 Upgrade-and-Backup：备份就三样（instance/ 目录、.env 里的三个密钥、录像），升级就四步（git pull → 装依赖 → npm ci && npm run build → 重启服务）。
This page collects the questions people hit first, grouped by topic. Every answer is grounded in the repository's own documentation and code — and where the project has no such feature, it says so plainly instead of hedging.
What is the default administrator account?
The initial credentials are admin / admin123 (a deployment can set a different password with BASTION_ADMIN_PASSWORD). The first sign-in forces a password change; you cannot skip it. If the administrator password is lost, do not reinstall: run python run.py --reset-admin on the server and enter a new password.
How many failed logins before the account is locked?
Five consecutive failures lock the account for 15 minutes by default (BASTION_LOGIN_MAX_FAILURES=5, BASTION_LOGIN_LOCK_MINUTES=15). During the lockout even the correct password is refused, and both successful and failed logins are audited. Wait out the lockout, or have an administrator reset the password.
Is LDAP / SSO / two-factor authentication supported?
No. Accounts are local to the bastion. A successful sign-in issues a JWT (kept in the browser as localStorage.bastion_token, sent as Authorization: Bearer <token>); the SSH gateway authenticates with a password or a public key. There is no LDAP / OIDC / SAML / TOTP implementation and no configuration switch for one, so do not plan around connecting Active Directory.
What is the difference between "super administrator" and an ordinary administrator?
There are four built-in roles: admin (permission array ["*"]), ops (17 permission codes), auditor (9) and viewer (4). What the UI labels "super administrator" is the admin role: it ignores the access-grant table and can see every host. Ordinary administrators and operators see exactly what grants allow. Do not do day-to-day work with the super-admin account.
Which protocols are supported?
SSH (port 22 or a custom port), WinRM (5985 HTTP / 5986 HTTPS) and RDP (3389). One host can carry several protocol endpoints (the host_protocols table, unique on (host_id, protocol) — at most one endpoint per protocol per machine).
A Windows box needs both remote desktop and a command line — do I create two hosts? No. Create one host record, multi-select "Windows (command line + remote desktop)" under protocol entries, then fill in the WinRM port and the RDP port separately. Legacy duplicate records for the same address (from the era when each protocol was its own host) can be merged with the row's "Merge" action: accounts, grants and protocol endpoints all move onto the target record, the source record is then deleted, and session history — being audit data — is never rewritten.
Can legacy systems such as Windows Server 2003 / XP open a remote desktop here?
No — that is a capability boundary, not a setting. Their RDP only speaks TLS 1.0 with the standard RDP security layer; the project already relaxes the handshake into a compatibility mode and gets the session far enough that the target replies with data, but ironrdp-wasm in the browser still ends in decode error. The honest conclusion is: use the built-in Windows "Remote Desktop Connection" for such machines. Setting the host's "RDP security layer" to "Force SSL" bypasses NLA and makes the failure reason and the way forward appear in the alert, the session end reason and the audit trail.
How do I quickly test whether a host is reachable?
Use "Test connection" on the host row; add ?protocol=ssh|winrm|rdp to test one endpoint. For SSH it prints both the target's and the bastion's SSH version, which separates a version-negotiation problem from an account or network one.
The web terminal is stuck on "connecting". What now?
Nine times out of ten the reverse proxy is not passing WebSocket upgrades through: /socket.io/ needs the Upgrade and Connection headers (see the Nginx snippet in Install-and-Deploy). If it works against 127.0.0.1:5000 but not through the domain, this is almost certainly why.
How do I troubleshoot a Windows host that will not connect?
First check that WinRM is enabled on the target (Enable-PSRemoting -Force) and that the port matches (HTTP 5985 / HTTPS 5986 — filling in 5986 switches to TLS). Then confirm the account credentials, the WinRM auth method (NTLM by default) and the target's configuration. For RDP, check the port and the "RDP security layer"; legacy systems as above.
Why do more / pause / Read-Host not work in a WinRM session, while cd persists?
WinRM runs each command separately on the target: in-process environment variables and custom variables do not persist, but the current directory (cd) does. Interactive programs (paging, waiting for input) have no real console and are not supported — the three lines of guidance at the top of the session say exactly this.
How do I transfer files from a terminal? For Linux hosts, use "File manager" on the terminal toolbar (SFTP). WinRM has no SFTP channel, so that row does not render a "Files" button. File operations go through the same grants and policies as the terminal.
If I close the terminal window, does the session stay alive? No. One tab is one session; closing the window ends it (the server records the end reason). If a remote-desktop window is killed forcibly, the recording saved is the part the server closed out automatically — it is not lost entirely.
Can audit records be deleted?
File-operation records can be deleted (POST /api/audits/files/delete), and the deletion itself leaves a record. Command and session records expose no "edit the content" path; the design goal is deletable, yet detectable — every row carries a hash chain.
How do I verify the hash chain myself?
The repository ships an offline verifier: from bastion-backend/, run python tools/verify_audit_chain.py. The rule is explicit: empty hash rows before the chain starts are legitimate legacy rows from an older database; an empty hash row after the chain started is reported as an anomaly (blanking a hash counts as changing it).
How are asset credentials stored?
Encrypted at rest with Fernet (key file bastion-backend/instance/fernet.key), and never echoed back in plain text in the UI. Remote desktop is the one exception: CredSSP needs the password handed to the browser, and that step writes an explicit rdp_credential_reveal audit entry.
What happens if a key file is lost?
Lose secret.key and every JWT becomes invalid (everyone signs in again; no data loss). Lose fernet.key and the stored asset passwords become undecryptable — they must be re-entered. That is why backups must include the whole instance/ directory.
Which model does the AI use, and what must be configured?
Put DEEPSEEK_API_KEY in bastion-backend/.env and restart the service. Without it, /api/ai/chat returns 400 AI_NOT_CONFIGURED and the page says "尚未配置 DEEPSEEK_API_KEY（写入 bastion-backend/.env 后重启服务）".
Will the AI just run commands on its own?
Sensitive operations stop and wait for an administrator to approve them on the spot (audited as ai_tool_confirm) before anything executes. What the user asked, what the AI answered, which tools it called and who approved them are all auditable under "Audit Center → AI conversation audit".
Can I ask the AI from inside a web terminal?
Yes: type /ask-ai <question> in the session. The answer streams back into the terminal, and the whole exchange is audited like any other operation.
Do I need to install a database?
No. The default is a single SQLite file, bastion-backend/instance/bastion.db, with no external database dependency.
Which ports are used?
The backend API (and the served frontend) on 5000; the SSH gateway on 2222; the frontend dev server on 8000 (npm run dev). In production, reverse-proxy 5000 with Nginx — and remember to pass WebSocket upgrades through.
How do I ship a frontend change?
npm run build produces ant-design-pro/dist/, which the backend serves. Note the backend only checks for dist/index.html at startup: build after starting the backend and the page shows "未发现前端构建产物…仅提供 API" — restart the backend once.
What are the runtime requirements?
Backend: Python ≥ 3.11 (3.13 in development; dependencies in bastion-backend/requirements.txt). Frontend: Node ≥ 22 (that is what ant-design-pro/package.json declares under engines.node; the root README's "≥ 20" is the older, looser phrasing — 22 is the safe target).
How do I back up and upgrade?
See Upgrade-and-Backup: three things to back up (the instance/ directory, the three keys in .env, and recordings) and four steps to upgrade (git pull → install dependencies → npm ci && npm run build → restart the service).
相关页面 / Related pages: Troubleshooting · Upgrade-and-Backup · Install-and-Deploy · Home
很高兴认识你，陌生人！ 我是一名初二学生，在中国新疆读初中。英语和写的代码都还在慢慢练，这份手册也还在补，请大家多多谅解，也欢迎直接指正。
Nice to meet you, stranger! I'm an eighth-grade student in Xinjiang, China. My English and my code are still a work in progress, and so is this manual — please bear with me (and tell me if you can).
AutoOps 堡垒机 · 使用手册
起步
资产与权限
干活
查账与维护
AutoOps Bastion · Manual
Getting started
Assets and permissions
Work
Audit and upkeep