frappe-manager

Frappe Manager

使用 Frappe Manager（FM）管理基于 Docker 的 Frappe 开发环境。

适用场景

• 设置本地 Frappe 开发环境
• 创建隔离的测试环境
• Agent 驱动的开发（氛围编程）工作流
• 无需完整的 bench 设置即可快速原型开发
• 在多台机器上创建可复现的环境

所需输入

• 已安装并运行的 Docker
• Python 3.11+ 和 pipx
• 站点/bench 名称
• 要安装的应用（frappe、erpnext、hrms、自定义应用）
• 环境类型（dev/prod）

操作步骤

0) 安装 Frappe Manager

# Install via pipx
pipx install frappe-manager

# Enable shell completion
fm --install-completion

1) 创建站点

# Basic site (frappe only)
fm create mysite

# Site with ERPNext
fm create mysite --apps erpnext:version-15

# Site with multiple apps
fm create mysite --apps erpnext --apps hrms --environment dev

# Production site with SSL
fm create example.com --apps erpnext --env prod --ssl letsencrypt

2) 管理站点

# List all sites
fm list

# Start/stop site
fm start mysite
fm stop mysite

# View site info
fm info mysite

# View logs (follow)
fm logs mysite -f

# Delete site
fm delete mysite

3) 开发工作流

# Access shell inside container
fm shell mysite

# Inside container - common commands:
bench new-app my_custom_app
bench --site mysite install-app my_custom_app
bench --site mysite migrate
bench build --app my_custom_app
bench --site mysite run-tests --app my_custom_app

# Exit shell
exit

# Open in VSCode
fm code mysite

# Open with debugger
fm code mysite --debugger

4) Agent 驱动的开发

适用于开发 Frappe 应用的 AI Agent：

# 1. Setup: Create fresh environment
fm create testsite --apps erpnext:version-15 --environment dev
fm start testsite

# 2. Develop: Enter shell, create app
fm shell testsite
bench new-app my_app
bench --site testsite install-app my_app
# ... make code changes ...
exit

# 3. Test: Run tests
fm shell testsite
bench --site testsite run-tests --app my_app
exit

# 4. Verify: Check logs
fm logs testsite -f

# 5. Reset if needed: Start fresh
fm stop testsite
fm delete testsite
fm create testsite --apps erpnext:version-15 --environment dev

5) 内部服务管理（fmx）

在容器内，使用 fmx 控制服务：

fm shell mysite

fmx status      # Check service status
fmx restart     # Restart Frappe services
fmx start       # Start services
fmx stop        # Stop services

验证

• 可通过 http://mysite.localhost 访问站点
• 可使用管理员凭据登录（默认值：admin/admin）
• 已安装并显示自定义应用
• 测试可在容器内成功运行
• 日志中没有严重错误

故障模式 / 调试

• Docker 未运行：启动 Docker 守护进程
• 端口冲突：使用不同的站点名称，或检查端口 80/443
• 无法访问站点：通过 fm list 检查状态，尝试运行 fm start
• 应用安装失败：通过 fm logs 检查错误
• 启动缓慢：首次运行会下载镜像，请耐心等待

升级处理

• 有关高级 Docker 配置，请参阅 references/docker-config.md
• 有关 SSL 问题，请参阅 references/ssl-setup.md
• 有关 bench 命令，请参阅 references/bench-commands.md

参考

• references/fm-commands.md - 完整的 FM 命令参考
• references/agent-workflow.md - Agent 开发模式
• references/bench-commands.md - 容器内的 Bench CLI
• https://github.com/rtCamp/Frappe-Manager

注意事项

• 操作前务必备份：进行重大更改或更新前，运行 fm backup <site>
• 使用具名站点：避免使用通用名称，使用描述性站点名称以便识别项目
• 检查 SSH 访问权限：安装应用前，确保已为私有仓库配置 SSH 密钥
• 确认 Docker 状态：操作前运行 fm doctor 检查 Docker 和 FM 的运行状况
• 使用 fm shell 执行命令：运行 bench 命令前，务必先进入容器 shell

常见错误

错误	失败原因	修复方法
在 fm shell 外运行 bench 命令	出现“Command not found”或操作了错误的站点	务必先运行 fm shell <site>
站点上下文错误	操作影响了错误的站点	检查提示符是否显示正确的站点；使用 bench --site <site>
重建时缺少卷	数据丢失	使用 fm recreate --keep-volumes，或先备份
未检查 fm doctor	配置问题未被发现	运行 fm doctor 诊断问题
在站点 URL 中使用 localhost	DNS 解析问题	本地访问时使用 <site>.localhost 格式
重启后忘记运行 fm start	无法访问站点	运行 fm start <site> 或 fm start --all