coze-dev · Zwen092 · Dec 13, 2025
@@ -82,6 +82,49 @@ Deployment steps:
    * [Code Development and Testing](https://github.com/coze-dev/coze-studio/wiki/7.-Development-Standards#code-development-and-testing): Learn how to perform secondary development and testing based on the open-source version of Coze Studio.
    * [Troubleshooting](https://github.com/coze-dev/coze-studio/wiki/7.-Development-Standards#troubleshooting): Learn how to view container states and system logs.
 
+### Local Debugging with Delve
+
+This project supports remote debugging of the `coze-server` service using [Delve](https://github.com/go-delve/delve). This is achieved through a specific Dockerfile and a `docker-compose` configuration.
+
+#### Relevant Files
+
+- **`backend/DockerFile-local-debug`**:
+  This Dockerfile builds the Go application with debug symbols. It installs the `delve` debugger and ensures the application starts with `delve` attached.
+
+- **`docker/docker-compose-local-debug.yml`**:
+  This `docker-compose` file starts the local debugging environment for the entire application. It uses `backend/DockerFile-local-debug` to build the `coze-server` service and exposes the debugger port `40000`.
+
+#### Running the Debug Environment
+
+1.  **Navigate to the `docker` directory**:
+    ```bash
+    cd docker
+    ```
+
+2.  **Start the services**:
+    Use the `docker-compose-local-debug.yml` file to build and start all services.
+    ```bash
+    docker-compose -f docker-compose-local-debug.yml up --build
+    ```
+    The `coze-server` service will start inside the container, listening on port `40000` for a debugger to connect.
+
+#### Connecting the Debugger
+
+You can connect using any IDE that supports Delve remote debugging. Here are example for GoLand.
+
+1.  Go to `Run -> Edit Configurations...`.
+2.  Click the `+` button to add a new configuration and select `Go Remote`.
+3.  Configure the settings:
+    *   **Name**: `Connect to Delve (Docker)` (or any descriptive name)
+    *   **Host**: `127.0.0.1`
+    *   **Port**: `40000`
+    *   **Go version**: Select your Go SDK.
+4.  Apply and Save the configuration.
+5.  With the `coze-server` running in debug mode (as described in "Running the Debug Environment"), select the newly created run configuration and click the debug icon (🐞).
+
+You should now be able to set breakpoints, inspect variables, and step through code in the `coze-server` service as if you were debugging a local application.
+
+
 ## Using the open-source version of Coze Studio
 > Regarding how to use Coze Studio, refer to the [Coze Development Platform Official Documentation Center](https://www.coze.cn/open/docs) for more information. Please note that certain features, such as tone customization, are limited to the commercial version. Differences between the open-source and commercial versions can be found in the **Feature List**.
 

@@ -84,6 +84,49 @@ Coze Studio 的后端采用 Golang 开发，前端使用 React + TypeScript，
    * [代码开发与测试](https://github.com/coze-dev/coze-studio/wiki/7.-%E5%BC%80%E5%8F%91%E8%A7%84%E8%8C%83#%E4%BB%A3%E7%A0%81%E5%BC%80%E5%8F%91%E4%B8%8E%E6%B5%8B%E8%AF%95)：了解如何基于 Coze Studio 开源版进行二次开发与测试。
    * [故障排查](https://github.com/coze-dev/coze-studio/wiki/7.-%E5%BC%80%E5%8F%91%E8%A7%84%E8%8C%83#%E6%95%85%E9%9A%9C%E6%8E%92%E6%9F%A5)：了解如何查看容器状态、系统日志。
 
+### 本地调试 (Local Debugging with Delve)
+
+本项目支持使用 [Delve](https://github.com/go-delve/delve) 对 `coze-server` 服务进行远程调试。
+
+#### 相关文件
+
+- **`backend/DockerFile-local-debug`**:
+  这个 Dockerfile 用于构建一个包含调试信息的 Go 应用。它会安装 `delve` 调试器，并确保应用在启动时附加了 `delve`。
+
+- **`docker/docker-compose-local-debug.yml`**:
+  这个 `docker-compose` 文件用于启动整个应用的本地调试环境。它会使用 `backend/DockerFile-local-debug` 来构建 `coze-server` 服务，并暴露调试器端口 `40000`。
+
+#### 运行调试环境
+
+1.  **切换到 `docker` 目录**:
+    ```bash
+    cd docker
+    ```
+
+2.  **启动服务**:
+    使用 `docker-compose-local-debug.yml` 文件来构建并启动所有服务。
+    ```bash
+    docker-compose -f docker-compose-local-debug.yml up --build
+    ```
+    `coze-server` 服务将在容器内启动，并监听 `40000` 端口等待调试器连接。
+
+#### 连接调试器
+
+你可以使用任何支持 Delve 远程调试的 IDE 进行连接。以下为 GoLand 的配置示例。
+
+1.  进入 `Run -> Edit Configurations...`。
+2.  点击 `+` 按钮添加新配置，选择 `Go Remote`。
+3.  配置以下设置：
+    *   **Name**: `Connect to Delve (Docker)` (或任何有描述性的名称)
+    *   **Host**: `127.0.0.1`
+    *   **Port**: `40000`
+    *   **Go version**: 选择你的 Go SDK。
+4.  应用并保存配置。
+5.  在 `coze-server` 以调试模式运行后（如“运行调试环境”所述），选择新创建的运行配置并点击调试图标 (🐞)。
+
+现在你应该可以像调试本地应用一样，在 `coze-server` 的代码中设置断点、检查变量和执行代码了。
+
+
 ## 使用 Coze Studio 开源版
 > 关于如何使用 Coze Studio，可参考[扣子开发平台官方文档中心](https://www.coze.cn/open/docs)获取更多资料。需要注意的是，音色等部分功能限商业版本使用，开源版与商业版的功能差异可参考**功能清单**。
 

@@ -0,0 +1,81 @@
+# Stage 1: Builder for Go application
+FROM golang:1.24-alpine AS builder
+
+WORKDIR /app
+
+# Install build dependencies for Go
+RUN apk add --no-cache git gcc libc-dev
+
+# Copy go.mod and go.sum first to leverage Docker cache
+COPY backend/go.mod backend/go.sum ./
+RUN go mod download
+
+RUN go install github.com/go-delve/delve/cmd/dlv@latest
+
+# Copy the entire backend source code
+COPY backend/ ./
+
+# Build the Go application
+RUN go build -gcflags="all=-N -l" -o /app/opencoze main.go
+
+
+
+# Stage 2: Final image
+FROM alpine:3.22.0
+
+WORKDIR /app
+
+# Install runtime dependencies for Go app and base for Python
+# pax-utils for scanelf, python3 for running Python, python3-dev for headers/shared libs
+# bind-tools for nslookup etc., file for debugging file types
+RUN apk add --no-cache pax-utils python3 python3-dev bind-tools file deno curl
+
+RUN deno run -A jsr:@langchain/pyodide-sandbox -c "print('Hello, World')"
+
+# Install Python build dependencies, create venv, install packages, then remove build deps
+RUN apk add --no-cache --virtual .python-build-deps build-base py3-pip git && \
+    python3 -m venv --copies --upgrade-deps /app/.venv && \
+    # Activate venv and install packages
+    . /app/.venv/bin/activate && \
+    # If you want to use other third-party libraries, you can install them here.
+    pip install urllib3==1.26.16 && \
+    pip install --no-cache-dir h11==0.16.0 httpx==0.28.1 pillow==11.2.1 pdfplumber==0.11.7 python-docx==1.2.0 numpy==2.3.1 && \
+    # Deactivate (optional, as RUN is a new shell)
+    # deactivate && \
+    # Remove build dependencies
+    apk del .python-build-deps
+
+
+# Copy the built Go binary from the builder stage
+COPY --from=builder /app/opencoze /app/opencoze
+
+COPY --from=builder /go/bin/dlv /usr/local/bin/dlv
+
+# Copy Python application scripts
+COPY backend/infra/document/parser/impl/builtin/parse_pdf.py /app/parse_pdf.py
+COPY backend/infra/document/parser/impl/builtin/parse_docx.py /app/parse_docx.py
+COPY backend/infra/coderunner/impl/script/sandbox.py /app/sandbox.py
+
+
+# Copy static resources
+# COPY backend/static /app/resources/static/
+COPY backend/conf /app/resources/conf/
+COPY docker/.env.example /app/.env
+# COPY docker/.env.ve /app/.env
+# COPY docker/cert.pem /app/cert.pem
+# COPY docker/key.pem /app/key.pem
+
+# Set PATH to prioritize venv's binaries
+ENV PATH="/app/.venv/bin:${PATH}"
+# ENV LD_LIBRARY_PATH="/usr/lib:${LD_LIBRARY_PATH}" # Keep commented for now
+
+# Ensure python scripts and venv executables are executable
+RUN chmod +x /app/parse_pdf.py /app/parse_docx.py  && \
+    find /app/.venv/bin -type f -exec chmod +x {} \;
+
+
+EXPOSE 8888 40000
+
+ENV SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
+
+CMD ["dlv", "exec", "/app/opencoze", "--listen=:40000", "--headless=true", "--api-version=2", "--accept-multiclient"]