启动与访问
Backlog.md 内置了一个现代化的 Web 界面，让你在浏览器中直观管理任务、看板、里程碑和文档。通过 backlog browser 命令即可一键启动。
启动 Web 服务器
打开终端，进入 Backlog.md 项目目录，执行以下命令：
backlog browser
服务器默认绑定到 127.0.0.1（回环地址），启动后会自动在默认浏览器中打开界面地址。控制台会显示类似如下信息：
🚀 Backlog Web UI running at http://localhost:6420
默认仅监听本机请求，同一网络中的其他设备无法直接访问。
命令行选项
指定端口
如果默认端口 6420 已被占用，可通过 --port 参数指定其他端口：
backlog browser --port 8080
启动后，在浏览器中访问 http://localhost:8080 即可进入界面。
端口占用时自动换端口
默认情况下（配置项 autoPort: true），若默认端口已被占用，服务器会自动扫描后续可用端口并在控制台打印真实地址，无需手动指定，也不会直接报错退出：
🚀 Backlog Web UI running at http://localhost:6421
自动扫描只接受用户端口范围（1024–65535）内的端口，会拒绝操作系统临时分配的随机高位端口。若把配置项 autoPort 设为 false，端口占用将恢复为直接报 EADDRINUSE 错误（此时可用 --port 显式指定）。该开关也可在 Web 界面「设置」面板中切换。
禁止自动打开浏览器
若不需要自动弹出浏览器窗口（例如在远程服务器或 CI 环境中运行），添加 --no-open 参数：
backlog browser --no-open
此时需手动复制控制台输出的地址到浏览器中访问。
指定绑定主机
默认情况下 Web 服务器只绑定 127.0.0.1，适合本地开发。若需要让局域网内其他设备访问，可使用 --host 显式指定：
# 监听所有接口（开放局域网访问）
backlog browser --host 0.0.0.0
通配绑定时，控制台会打印具体的 LAN IPv4 地址，并提示当前 API 未认证。浏览器会自动打开第一个可用的 LAN 地址。你也可以绑定到某个具体网卡：
backlog browser --host 192.168.1.100
使用自定义浏览器
在 devcontainer 或没有默认浏览器的容器中，可通过 BROWSER 环境变量指定启动命令：
BROWSER=/usr/bin/chromium backlog browser
BROWSER 被视为单个可执行路径（去除包裹引号，不会拆分或 shell 求值），URL 作为独立参数传入。未设置时按平台自动回退：open（macOS）、cmd /c start（Windows）、xdg-open（Linux）。
组合使用
backlog browser --port 3000 --no-open
BROWSER=/usr/bin/chromium backlog browser --host 127.0.0.1 --port 8080
技术特性
Web 界面采用以下技术构建，确保流畅的使用体验：
- React：组件化交互界面，页面切换无刷新
- Tailwind CSS v4：现代化样式系统，界面简洁统一
- 响应式布局：自动适配桌面端和移动端屏幕尺寸
- 暗黑模式：支持系统主题自动切换，也可手动切换亮色 / 暗色模式
实时同步
Web 界面与本地 Markdown 文件保持实时同步：
- 在浏览器中修改任务状态或内容，会自动写回到对应的 Markdown 文件
- 在外部编辑器（如 VS Code、Vim）中修改文件，Web 界面会即时刷新显示最新内容
- 无需手动刷新页面，所有视图均通过 WebSocket 实时更新
界面布局
Web 界面采用经典的左右布局：
- 左侧边栏：占据固定宽度，展示导航菜单和文件树
- 右侧内容区：占据剩余空间，展示任务、看板、文档或 Wiki 内容
调整侧边栏宽度
侧边栏右边缘有一条贯穿全高的可拖拽把手，将鼠标移到该把手上、光标变为左右箭头时按住拖拽，即可调整侧边栏宽度。拖拽过程中会显示一条蓝色 ghost bar 预览最终位置，松开鼠标后宽度立即生效并自动保存到浏览器本地存储（localStorage），下次打开时恢复上次设置的宽度。
- 最小宽度限制为 200px，防止侧边栏缩至不可见
- 最大宽度限制为 500px，避免占用过多内容区空间
折叠侧边栏
侧边栏中部右侧有一个折叠/展开按钮（箭头图标），点击可将侧边栏收起为仅显示图标的最窄模式，再次点击恢复展开。折叠状态与宽度设置均保存到 localStorage。
停止服务
在运行 backlog browser 的终端中按下 Ctrl + C，即可停止 Web 服务器。所有已保存的更改均已写入文件系统，数据不会丢失。
加载指示
Web 界面的加载反馈分为两层：
- 首次加载：看板区域显示与真实列布局一致的骨架屏（呼吸动画的幽灵列），中央为加载环；项目尚未初始化的等待画面同样显示加载环
- 后台索引：跨分支索引等后台工作进行时，头部右侧显示一个状态 chip（展示当前阶段文案，悬停可见完整信息），头部下缘附带扫动进度条；已加载的看板与树保持可交互，不会被骨架屏覆盖
加载动画在系统开启「减少动态效果」（reduced motion）时仍然播放——加载进度属于必要反馈而非装饰，静止的加载环在远程桌面、虚拟机等环境下容易被误读为卡死。
作为常驻服务运行
backlog browser --no-open 只启动服务、不打开浏览器，适合注册为开机自启的常驻服务（doc-003）。要点：每个项目一个独立服务与独立端口，工作目录必须指向项目根。
- Linux（systemd 用户服务）：创建
~/.config/systemd/user/backlog-browser-<项目>.service，ExecStart为backlog browser --no-open --port <端口>，Restart=on-failure；执行loginctl enable-linger后无需登录会话即可开机启动；项目较多时可用模板单元backlog-browser@.service - macOS（launchd）：在
~/Library/LaunchAgents/放置 Label 唯一的 plist，配置RunAtLoad与KeepAlive；注意 Apple Silicon 与 Intel 的二进制路径分别为/opt/homebrew/bin/backlog与/usr/local/bin/backlog - Windows：用计划任务（
New-ScheduledTaskAction，-AtLogOn触发）实现登录自启；需要无人登录也常驻时，用 NSSM 包装为真正的 Windows 服务以获得自动重启